Excellent summary.

Typo for shebang ?

Typo for shebang ?

Fixed.

Excellent summary.

Thanks :).

Since recently, Docs stylesheet automatically generates a table of contents.
There is no need to specify :toc: any more.

Is % prefix missing from ansible_collection_build and ansible_collection here?
Other macros in this document are written with that prefix,
and using it seems to be the standard way to do that also elsewhere.

In my opinion, this statement does not add anything here.
It goes without saying that tooling and Guidelines are subject to change and improvement.

In my opinion, this statement does not add anything here.
All packages must follow the rules for the License: field.
That does not have to be repeated for Ansible packages repeatedly.

Is %check missing from this example?

Disclaimer for all my comments above:
I am not a member of the Packaging Committee.
My review comments are completely unofficial.

Is % prefix missing from ansible_collection_build and ansible_collection here?
Other macros in this document are written with that prefix,
and using it seems to be the standard way to do that also elsewhere.

Fixed.

Is %check missing from this example?

Indeed, it is. I've fixed it.

In my opinion, this statement does not add anything here.
It goes without saying that tooling and Guidelines are subject to change and improvement.

I guess you kind of have a point. The idea was for packagers to be prepared for this to change in the future. I'm thinking that I might have this fixed before the "final draft," so I'll leave it here more as a reminder for now.

Since recently, Docs stylesheet automatically generates a table of contents.
There is no need to specify :toc: any more.

It adds a table of contents to the beginning of the page. Notice the difference between https://docs.fedoraproject.org/en-US/packaging-guidelines/CMake/ (has :toc:) and https://docs.fedoraproject.org/en-US/packaging-guidelines/JavaScript/ (does not).

In my opinion, this statement does not add anything here.
All packages must follow the rules for the License: field.
That does not have to be repeated for Ansible packages repeatedly.

I mainly added it here so the legal team didn't complain about there being legal guidelines within the packaging guidelines. I'll remove that if there's consensus to do so.

I've force pushed to add two newlines between specfile sections in the example.

Since recently, Docs stylesheet automatically generates a table of contents.
There is no need to specify :toc: any more.

It adds a table of contents to the beginning of the page. Notice the difference between https://docs.fedoraproject.org/en-US/packaging-guidelines/CMake/ (has :toc:) and https://docs.fedoraproject.org/en-US/packaging-guidelines/JavaScript/ (does not).

That it does. My point was that even without it, there is a table of contents visible.
Either on the right, or on top, depending on viewport width.
And for narrow viewports, the automatic one is only visible if :toc: is not specified.

Anyhow, I just wanted to point out that :toc: is not needed to get a table of contents any more.
I am not aware of any style guide or such saying that you should not include it,
so please do if you prefer to do so.

Are these really named without the "ansible_" prefix? If so, the inconsistency seems a bit odd.

This caveat is interesting; now I wonder if one method is preferred. From a macro standpoint is it simpler to just stuff a list of files in a string than to write out a file (which probably needs Lua) and so having consistency across different sets of macros might be difficult if it's even something we wanted.

Yes; currently, %ansible_collection_install, %ansible_test_unit, and %ansible_collection_files rely on the %collection_namespace and %collection_name macros being set in the specfile. I am working on refactoring the macros to extract these values from the galaxy.yml metadata file and remove the need for these macros. This will require a file list.

From a macro standpoint is it simpler to just stuff a list of files in a string

That's true in some cases, but it won't work if you need to dynamically populate the %files section based on content from the extracted sources.

@gotmax23:

I am working on refactoring the macros to extract these values from the galaxy.yml metadata file and remove the need for these macros. This will require a file list.

Okay, I have completed this refactoring. The changes are available here if anyone has comments on it before I merge. The refactoring removes the need for %collection_namespace and %collection_name. This guidelines PR reflects the macro changes.

I'm removing the draft status. The ansible-packaging changes have been merged and the new version is now available in the buildroot, and I'm satisfied with the current state of the guideline text.

I've rebased this. What are the next steps here?

Commit 136e8f9e fixes this pull-request