typo

https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples].

Those examples are now outdated. My suggestion would be to import this page into the new docs repo too, and update it at the same time.

This integer MUST begin at 1 and MUST be incremented for each change made to the package

That's probably not related directly to this change, but: maybe this should be relaxed to say "MUST be incremented whenever the package is rebuilt in koji" (or something to that effect). People generally don't follow this guideline as written.

without rebuilding package for newer branches,

... rebuilding the package

typo: pacakge

typo: must → most

typo: prerelasee

... or a snapshot

typo: previse

Maybe drop the part about CVS? It'll only confuse anyone below 30.

the date in eight digit +YYYYMMDD+ format.

Is this really necessary? Including the date is additional work that doesn't really bring that much benefit for many cases (*).
The alternative scheme where a number is included ^1.git01ABCDEF, ^2.git01ABCDAA, etc, should also be allowed
by guidelines.

(*) For example, systemd "upstream" is a snapshot of a branch with backported patches (as in https://github.com/systemd/systemd-stable/commits/v242-stable), there is no meaningful "date", because the time when the patch was written is non-monotonous, so cannot be used here, and the time when the patch was backported is not particularly interesting, and the time when the snapshot was packaged doesn't say anything about the contents.

== Release: tag

Why describe Release tag before Version tag? I think the order should be switched.

@tibbs In order to get the ball rolling, I've requested the carat version modifier to be backported to RHEL 8.

I figure if I put the request in now, we can see it land in EL8 around the same time that Fedora 31 does. :wink:

That is unrelated to this change. I mentioned the need to work on these examples in the open ticket for this issue.
The page is in the wiki to enable the community to provide examples, but again that's completely unrelated to this change.

Because that puts the two shortest sections at the front, so users who want to know what goes in the release field don't have to skip the description of the Version: field.

Unrelated to this change. Neverless, the guideline is correct. Change version, reset release. It's pretty simple, and I do think most people follow it. You wouldn't change Version and leave Release: at 27, only setting it back to one the moment you want to build.

This is unrelated to the change in question. Please bring it up separately.

Unrelated to this change. Besides, it's 100% valid, isn't it? Feel free to open a separate ticket about it if you like.

Because that puts the two shortest sections at the front, so users who want to know what goes in the release field don't have to skip the description of the Version: field.

That's not a good idea. The page is divided into sections so that people can jump to the right spot if they want. The text itself should be ordered logically, not by section size.

Unrelated to this change. Neverless, the guideline is correct. Change version, reset release. It's pretty simple, and I do think most people follow it. You wouldn't change Version and leave Release: at 27, only setting it back to one the moment you want to build.

No. As stated, every commit in dist-git would need a bumped release entry.

Re the other comments: since the text is being completely rewritten anyway, maybe it is easiest to trim and remove outdated parts. I know that strictly speaking those items could be done separately, but I don't think it does either me or the packaging committee any favours if I now open 10 tickets about modification to the same few paragraphs of text.

What's the status here? Is this PR still pursued?

This is obsoleted by #1073, and can be closed.