[WIP, needs vote before merging] collection_requirements.rst: update

[Andersson007]

It's time to revise and update the requirements if needed. Forum topic.

Goals:

• Simplify it if possible (content, wording), make it easier to read
• Exclude irrelevant requirements (including those that don't work/very hard to control)
• Make maintainers and reviewers 's lives easier

Any suggestions are appreciated (in not touched parts as well)

Post tasks:

• Update https://github.com/ansible-collections/overview/blob/main/collection_checklist.md after merging this PR if needed.

[oraNod]

Looks good @Andersson007 I've read through this a couple of times to try and come up with comments other than grammar nits but it seems fine. It looks a bit more straightforward now. I'll wait and see how the vote goes before approving in case there are additional changes.

[samccann]

https://github.com/ansible/ansible-documentation/pull/1422/files#diff-17918ba4d47cb68e11b669412c5ea11b87bd8b5944b04720c6b74d104c692829R253 (Not sure that link will work, but the galaxy docs links under Naming are no longer correct and should be updated.

[samccann]

Another general comment. The top sections are clear on MUST and SHOULD but as it gets later in the page, there is a lot of contextual information that tends to clutter the MUST etc. So maybe each section should start with the MUST sentences, and then under each, indent, and add the context.

So for example, under python compatibility , it could have controller environment and other environment subheadings with their MUST statements. Then under the MUST, indent and add the contextual details of what each python environment means.

The goal would be that a knowledgable collection maintainer can more easily skim the document to verify they meet all the MUST statements. But a newer collection creator still has the details they need to understand each MUST statement.

[Andersson007]

Looks good @Andersson007 I've read through this a couple of times to try and come up with comments other than grammar nits but it seems fine. It looks a bit more straightforward now. I'll wait and see how the vote goes before approving in case there are additional changes.

it's still WIP, the call was about bringing up thoughts of what else to kick out/simplify, just a fyi, thanks for the feedback!

[Andersson007]

Another general comment. The top sections are clear on MUST and SHOULD but as it gets later in the page, there is a lot of contextual information that tends to clutter the MUST etc. So maybe each section should start with the MUST sentences, and then under each, indent, and add the context.

So for example, under python compatibility , it could have controller environment and other environment subheadings with their MUST statements. Then under the MUST, indent and add the contextual details of what each python environment means.

The goal would be that a knowledgable collection maintainer can more easily skim the document to verify they meet all the MUST statements. But a newer collection creator still has the details they need to understand each MUST statement.

@samccann something like #1459 ? (not sure if it's a good idea to create a separate PR for that though..). Folks please take a look

[Andersson007]

This makes the requirements much tidier!

I found a few random suggestions to make. Take or leave them as you like.

Thanks a lot!

[felixfontein]

Two small improvements which I noticed while reading through this:

[Andersson007]

@briantist @acozine @gundalow @felixfontein @samccann @oraNod @ssbarnea thanks a lot for reviewing!

[patchback]

Backport to stable-2.17: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-2.17/7a744a1094c4b1103d457d0f33765a2d2173ca92/pr-1422

Backported as #1664

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.