Improve ansible PyPI README

[gotmax23]

The current README for ansible package on PyPI is not very informative IMO. Some of it has information that is only relevant to ansible-core. Additionally, it's missing important details about what the ansible package actually is and how it differs from ansible-core. The Branch Info section kind of touches on it but it's not detailed and is buried at the bottom.

• Prominently explain the difference between ansible-core and ansible.
• Remove ansible-core CI badge.
• Add section about reporting issues.
• Mention ansible-build-data

[gotmax23]

Relates: ansible-community/community-topics#173

I'd like more input from the community and SC before merging something like this

[mariolenz]

I think this is a very good idea. While we're at it, should we also change the Design Principles? They are still the ones from ansible-core and don't relate directly to the community package.

I'm not sure how to phrase it, but maybe something like adding an additional layer of quality management to the collections, make sure they are maintained, follow best practices, do not break any sanity tests...

And one other thing: You're linking to the Communication page which already mentions The Bullhorn. But maybe it would be worth to mention it explicitly somewhere in the Readme. Just an idea because I really like Bullhorn ;-)

[felixfontein]

While we're at it, should we also change the Design Principles? They are still the ones from ansible-core and don't relate directly to the community package.

I think most of them apply to Ansible in general, so I think they still fit.

I'm not sure how to phrase it, but maybe something like adding an additional layer of quality management to the collections, make sure they are maintained, follow best practices, do not break any sanity tests...

I would avoid listing anything that's already mentione in the collection requirements (https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst), but linking to that one is probably a good idea.

[mariolenz]

I would avoid listing anything that's already mentione in the collection requirements (https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst), but linking to that one is probably a good idea.

Good point. But I think we should add at least one design principle that's specific to the community package. Like "Create a 'batteries included' bundle of high-quality / extra QA'ed collections" or similar.

[gotmax23]

While we're at it, should we also change the Design Principles? They are still the ones from ansible-core and don't relate directly to the community package.

I think most of them apply to Ansible in general, so I think they still

I kind of agree with @mariolenz here. I think that section should have a stronger focus on the ansible package itself.

[gotmax23]

Design principals ideas:

• "Provide a curated bundle of quality collections that conform to the Collection Requirements" (suggested by @gotmax23) (remove quality suggested by @mattclay)
• "All batteries included" (suggested by @felixfontein)

[samccann]

just some nits

[oraNod]

Suggested change

	by the community, and it pulls in
	by the community and includes

[gotmax23]

It doesn't include ansible-core. ansible-core is a separate package. I'm fine with something other than pulls in, but I don't like include.

[felixfontein]

• "Provide a curated bundle of quality collections that conform to the Collection Requirements" (suggested by @gotmax23) (remove quality suggested by @mattclay)

  • "All batteries included" (suggested by @felixfontein)

I like Provide a curated bundle of collections that conform to the Collection Requirements (with CR being a link to the actual requirements).

[gotmax23]

I'm not sure it makes sense to mix ansible-core Design Principles with ansible specific ones.

[felixfontein]

It depends on what you think the 'ansible' package is. For me, the 'ansible' package is Ansible, which is ansible-core + collections. Then the ansible-core design principles also apply to Ansible.

The docsite for Ansible also contains (most of) the docsite of ansible-core, same for the changelog. So to me it does make sense.

[mariolenz]

It depends on what you think the 'ansible' package is. For me, the 'ansible' package is Ansible, which is ansible-core + collections.

Good point. Is ansible really the succesor of ansible 2.9, or is ansible-core the successor and the community package is "just" an add-on? Would be interesting to know how the core team thinks about this.

Then the ansible-core design principles also apply to Ansible.

I should say they do. The question is if they should be repeated here.

[samccann]

Good point. Is ansible really the succesor of ansible 2.9, or is ansible-core the successor and the community package is "just" an add-on? Would be interesting to know how the core team thinks about this.

At the time we were designing the docsite to handle the collections world, it was decided that Ansible the package would retain the 'ansible' name, So yes, imo, Ansible package is the successor to Ansible 2.9 and that's how we handled the docsite.

[felixfontein]

I should mention that not everyone agrees that this (treating the community package as the successor, and treating ansible-core as "a part of" ansible) was/is a good idea, and this is also related to the discussion what the exact ansible-core dependencies of ansible should be. See for example ansible-community/community-topics#84. There have been more discussions on this, but most were probably in community meetings (especially during the beginning of Ansible 2.10). (I don't think we should continue that discussion here though, if anyone wants to discuss it, either continue in the community issue I linked, or create a new one, whatever you think is more appropriate.)

[gotmax23]

In the README, I used ansible (lowercase, monospace) to refer to the package and left Ansible (capitalized) to refer to the project/ecosystem in general.

[gotmax23]

Force pushed to fix a rst syntax/formatting issue

[felixfontein]

There is now a vote on merging this as-is: ansible-community/community-topics#186

Further changes/improvements (like on the design principles) can be done in (a) follow-up PR(s).

[felixfontein]

The vote concluded and was to merge this as-is, so let's merge this 🎉