missing empty line

please reformat according to semantic line breaks

After looking through the changes, I don't see anything obvious that needs changing, and I expect that you have already tested using the templates for packages to verify that they actually produce correct packages.

That said, the current draft adds only a bare minimum of text to the Guidelines, and only includes the current version of the example templates (which contain annotations explaining the usage) on top of that.

The current structure probably makes the documentation hard to parse for readers who just want to look up usage information for one specific macro (and its arguments and which environment it expects), because they have to look through the templates for that information.

It would be nice to have at least a small overview in textual form for the Guidelines themselves. For example, which macros are available (%forgemeta, %forgeurl, %forgesource, ...) and the macros they expect to be set when they are called (exactly one of version, tag, commit, branch, andforgeurl, etc.).

For example, adding a paragraph like this ↓ would be easy, and would probably give most users almost all the information they need, and could refer them to the templates for more details:

Available macros for processing forge sources:
- %forgemeta: processes forgeurl, tag, Version, commit, branch macros (with and without number prefix), and computes the resulting %forgesource values
- %forgesource (with and without number prefix): provides Source URLs, use for the Source tag (with the appropriate number)
- %forgesetup: wrapper around the %autosetup macro, calling it with appropriate arguments

Maybe also mentioning regularly used arguments, like -a or -z N for %forgemeta and %forgesetup, and additional information on how the expected input macros have to be named for multiple sources (especially %versionN wasn't obvious to me).

I also expect this addition to blow up the length of the SourceURL page due to the included templates. Maybe that section could be extracted to a separate page, with a link to it below the explanatory text in the main SourceURL page.

First, thanks a lot for the review.

After looking through the changes, I don't see anything obvious that needs changing, and I expect that you have already tested using the templates for packages to verify that they actually produce correct packages.

The code corresponding to those templates has been merged and in use in rawhide since mid-october:
https://koji.fedoraproject.org/koji/buildinfo?buildID=1154732

The documentation could not be written before this merge, since the code review may request variable and macro renamings (the usual way to do those would be to have a single code + doc PR, with matching changes, but that's not how Fedora organized itself).

So the basic functionality is already in use and known to work. It will still need code fixes:

• when totally broken forges like bitbucket or pagure fix themselves, or
• when upstreams get really creative about their release tagging, like here: https://src.fedoraproject.org/fork/nim/rpms/redhat-rpm-config/c/9ad828b68da0065f27d9b01a1dd700a1d71fb28f

(I so which someone could beat some sense in git upstream so the x.y.z way of releasing pretty much everyone needs and uses is supported natively by git without room for human syntax “creativity”).

But that does not require any template update. That's just fixes, not changes to the overall design.

What could change templates is new features like:
https://pagure.io/go-rpm-macros/issue/3

But, not sure if I will ever bother to code it (or push it to Fedora if I code it for my own needs), given how my previous rounds of contributions are been received.

That said, the current draft adds only a bare minimum of text to the Guidelines, and only includes the current version of the example templates (which contain annotations explaining the usage) on top of that.

It's likely to be the only documentation that will ever be since the redhat-rpm-config maintainers do not want their package to document itself, so future code changes won't have any matching documentation unless someone finds the energy to bother with separate guidelines PR-ing.

The current structure probably makes the documentation hard to parse for readers who just want to look up usage information for one specific macro (and its arguments and which environment it expects), because they have to look through the templates for that information.

I'm not sure how useful “looking up usage information for one specific macro” would be. It all performs basically a single function. The splitting in multiple calls is a side-effect of the way rpm splits source and setup in different places of the spec, nothing more.

Yes the design is modular so you can replace parts of the processing with your own thing, but to do it safely without hitting all kinds of breakage you need to be aware of the high-level view. Otherwise you will change things, thinking it only matters at the point you do changes, and hit side effects in the next section of the spec.

Individual macro usage is already documented in the macro files themselves
https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/master/f/macros.forge

That makes sure the documentation does not stray too far from what the code does. But, it quickly gets overwhelming without the high level recommended usage template view.

If you feel strongly about it a can complete this PR with individual macro documentation but I fear that will be the same feel-good not needed documentation bloat that made people ignore https://fedoraproject.org/wiki/Forge-hosted_projects_packaging_automation and forced a complete documentation rewrite. Plus, it's almost sure to lose sync with the code quickly, since it won't be possible to document behavior changes in the commit that makes those changes.

I also expect this addition to blow up the length of the SourceURL page due to the included templates. Maybe that section could be extracted to a separate page, with a link to it below the explanatory text in the main SourceURL page.

I've no opinion one way or another, that's really getting in general guidelines editorial land, not the documentation of a specific feature.

@nim is this still actual version?

@ignatenkobrain it's still actual version (as in https://src.fedoraproject.org/rpms/redhat-rpm-config/pull-request/51), the user interface has seen no changes since last summer, the core has been extended to support pagure but without changes packager-side

there is no such package in Fedora.

So I have looked at this once more and I think more appropriate way would be to document macros instead of dumping huge specfiles.

@nim Can you please restructure this?

@ignatenkobrain the macros are incomprehensible without a template, because you have several lines of declarations interacting with one another.

That’s why the documentation is provided in template form, to give users example of various useful use patterns. And provided in actual templates they can copy in their own spec files, not prettified asciidoc text that can not be cut and pasted and will become obsolete as soon as the docs teams changes its rich text format (has happened to wiki doc)

A call-by call doc would be the kind of unreadable auto-generated doc you find in programming languages (worse, because rpm syntax does not provide structure helpers). But, if you want thins kind of thing, you can just copy the inlined comments in the templates, or the inline comments in the macro code.

Commit 179ad9af fixes this pull-request