The guidelines don't contain information on how to package. That's in the package maintainer docs here, for example:

https://docs.fedoraproject.org/en-US/package-maintainers/Packaging_Tutorial_GNU_Hello/

The tags you're talking about are rpm bits, so we link to the rpm documentation instead of noting them again in our docs. So the above page links also to:

https://rpm-software-management.github.io/rpm/manual/

There is a big difference between a packaging how to and a proper tag reference. The first is used by humans to packages stuff, the second is used to troubleshoot tools and automate stuff.

Versioning guidelines would be more useful if they are self-sufficient with relevant bit of info linked to external documentation. That's if Fedora doesn't invent its own ways of dealing with external spec. For example, uses Release: tag both for package release increment and for distribution info, which in RPM spec is covered by Os: and Distribution: tags.

To back up what @ankursinha has written, this is not something would be included in the packaging guidelines.

Regarding things being called tags, that terminology predates Fedora. I can't honestly say why %dist is called a tag. You could argue that the packaging guidelines should consistently call it a macro, and we might be willing to consider a separate PR that fixes that up, but the terminology goes very deep and even the document source file is named DistTag.adoc.

I just see a huge technical debt with regard to technical documentation here. Docs should avoid confusion, clarify things, explain terminology and help push things forward.

I agree that documentation could be better. However, the specifics that you claim are missing from Fedora Guidelines are not specific to Fedora, but RPM concepts, and documented in RPM docs ... for example, here's the list of tags: https://rpm-software-management.github.io/rpm/manual/tags.html

So basically, the Packaging Guidelines only document how we use RPM for packaging, but they obviously don't document how RPM itself works.

https://en.wikipedia.org/wiki/Curse_of_knowledge

The assumption that people know how RPM works is weak. People new to Fedora had no chances to learn it. Hence documentation is not relying on common concepts. Its logical connections has been whited out, with keys being elsewhere.

At the very least it could be crosslinked https://trac.edgewall.org/wiki/InterWiki
The proper way is still to add placeholders for every bit that matters.
And then turn that into a reference that answers most questions.

The Packaging Guidelines are not a packaging tutorial or a RPM manual. They are simply a set of common rules and practices that packagers should follow.

I didn't say it should be a tutorial. I say it should be a reference documentation.

Well, it's not supposed to be reference documentation either. It's a set of guidelines.

So what is the reference documentation then?

https://docs.fedoraproject.org/en-US/package-maintainers is what we have for Fedora specific bits.

Newcomers start here:

https://docs.fedoraproject.org/en-US/package-maintainers/Joining_the_Package_Maintainers/

It links to the tutorial:

https://docs.fedoraproject.org/en-US/package-maintainers/Packaging_Tutorial_GNU_Hello/

which includes links to the complete RPM reference manual:

https://rpm-software-management.github.io/rpm/manual/

The landing page of the guidelines says:

The Packaging Guidelines are a collection of common issues and the severity that should be placed on them. While these guidelines should not be ignored, they should also not be blindly followed. If you think that your package should be exempt from part of the Guidelines, please bring the issue to the Fedora Packaging Committee.

These documents cover the fine details of acceptable Fedora packaging and while they may include various examples they will not be particularly useful as a tutorial. They also do not cover the details and policies relating to gaining access to the Fedora repositories as a packager, or the mechanics of actually creating and releasing packages as part of the distribution. For documents which cover those issues, please see the following:

• Join the Package Maintainers
• New Package Process for Existing Contributors
• Creating RPM packages

If it's not clear enough from this text that folks should head to the package maintainer documentation for information on the process/pipeline, that can always be improved.