#656 pre/post-release version guidelines need major simplification for the git era
Closed: accepted 2 years ago Opened 2 years ago by zbyszek.

https://fedoraproject.org/wiki/Packaging:Versioning#Pre-Release_packages is very hard to read. Nowadays, most new packages use git, which is hardly mentioned in that page. It would be nice to cover the most common case of a git tag with some example that people can copy&paste without reading too much.

Suggested text:
https://fedoraproject.org/w/index.php?title=User:Zbyszek/PackagingDraft&oldid=477218


This is the diff:

https://fedoraproject.org/w/index.php?title=User%3AZbyszek%2FPackagingDraft&diff=477218&oldid=477217

The addition of a git example is probably useful, even if the other changes don't make it. Note that you probablyt want to look at the "bottom" of ticket 398 (https://fedorahosted.org/fpc/ticket/398) where this page has been changed a lot.

I'll add this to the meeting, but it's in a weird spot with 398.

Indeed, having two overlapping proposals for the same set of guidelines complicates things, especially with me also trying to clean up the existing guidelines at the same time.

Some of this diff is just cleanup and minor reorganization which I think we should just postpone considering until I'm done with the cleanup work I've promised.

The only change I'm seeing at first glance that's actually a functional change is under the proposal, the format the checkout identifier has been restricted (via "should") to a specific set, instead of allowing the packager to choose the format of the checkout string. I don't particularly have a problem with this, but it requires discussion.

Am I missing other functional changes? If not, then we can consider that one separately and I can write it into whatever the final form of the document ends up taking.

I wasn't aware that #398 had progressed so far. I agree that it's best to rebase any changes on top of our draft.

the format the checkout identifier has been restricted (via "should") to a specific set,

"should" still allows the packager to deviate if there's a good reason. But I think we should simplify things by recommending a standard form with the commit hash included.

Am I missing other functional changes?

In the git example I provided, the git hash is shortened to 7 characters. It's not specified as a guideline, but I was hoping that people would adopt that, so we don't have full sha1 hashes in package versions.

I also added "0 or 0.0 or similar" as the explicit version for git snapshots when there's no version whatsoever. I don't see this mentioned in your draft, although "0" is used in the kismet example. Would be nice to make this explicit.

Finally, an editorial thing: in your draft, the example for pre-release packages is hard to read. I think all examples should be converted to the flat version with comments on the right side (like "Example (complex pre-release and post-release scheme)"), and the comments indented.

Yes, "SHOULD" (as we're trying to be formal about it now) does permit the packager to deviate if necessary, with the requirement that they document. That's a good bit different from what we have now, which just says "must have the date; can have 13 characters of identifying content". (Which I'm sure is contradicted elsewhere in the document.)

I'm not opposed to the change; I just want to make it clear what the functional change actually is. And, really, mixing functional changes with cleanups only serves to confuse everyone, so it would probably be best if we tried to avoid that, especially with other things happening with this document. (I'm just glad I split it from the naming document before all of this started, or else it would be worse.)

In your message I can't tell whom you refer when you write "you". You mention "your draft" though while I have been working on something, I haven't produced a draft for this yet though I suppose you could have found it by browsing around. I haven't changed anything related to examples in it, though. Maybe you're talking about the draft in #398, though.

And, certainly, the examples need cleaning up, or rewriting, or moving to a separate more exhaustive page with examples, or... something. This document has been terrible for far too long. But also note that we don't have to go through a full formal revision process just to make the document prettier, and I'm happy to take suggestions for cleanup or reorganization at any time. (Especially since the look of, well, everything might be changing if we move the guidelines out of the wiki.)

I'm not opposed to the change; I just want to make it clear what the functional change actually is.

Ack.

And, really, mixing functional changes with cleanups only serves to confuse everyone

OTOH, cleanups should be applied to the page before official announcement. If a hundred people will be looking at it, it makes sense to prettify it before that. If I propose any changes in the future, I'll do my best to commit the cleanups separately from the functional changes, although wiki does not make this easy.

In your message I can't tell whom you refer when you write "you".
Maybe you're talking about the draft in #398,

Sorry, that's what I meant. For some reason I thought you (as in "tibbs") wrote it, but of course now I see that most work was done by Neal and Igor.

everything might be changing if we move the guidelines out of the wiki

+100 to that ;)

We discussed this at this weeks meeting (http://meetbot.fedoraproject.org/fedora-meeting-1/2016-10-20/fpc.2016-10-20-16.00.txt):

Just want to add that https://fedoraproject.org/wiki/User:Tibbs/VersioningCleanup has seen more work but is far from done.

Also, https://fedoraproject.org/wiki/User:Tibbs/VersioningCleanupExamples exists (and currently has pretty much nothing in it). The idea is to have at least one example for every single item in the guidelines document. If we move the examples, we have no need to be shy about having a whole pile of them.

https://fedoraproject.org/wiki/User:Tibbs/VersioningCleanup is now "complete" in that I believe it includes all of the information which was in the original document, except for the examples. I've stuffed all of the existing examples in https://fedoraproject.org/wiki/User:Tibbs/VersioningCleanupExamples but haven't worked on doing much in the way of formatting. I have made everything reference a generic package (as talking about "mozilla 1.4" is kind of embarrassing) and just need to make them look nice, separate them into categories and add links from the main document.

As for the cleanup, basically the info is all there that I want to present and I believe that following the document will produce identical versioning. The only functional changes should be:

  • Explicit mention of the already approved use of Version: 0.
  • Allowing "YYYYMMDD.githash" in the "snapshot information" field.
  • Explicit mention of the case where upstream uses invalid characters.
  • More detailed explanation of dealing with "unsortable" elements. The original guidelines just said to move the "non-numeric" portion to the "extra version information" and then added an exception to the exception saying that non-numeric portions are OK if they're "properly ordered simple versions", which wasn't really defined.

Technically the last point allows some instances of non-numeric versions which the old guidelines didn't. ("1.foo.2.3" would be allowed as long as upstream doesn't intend to release "1.bar.0.0" later.) I don't believe there are any examples of this anywhere, so it should make no real difference.

What I still need to do:

  • Redo the "Minor release bumps for old branches" bit. Integrate that into the regular sequence.
  • Think about how to present the complex case in a more understandable manner. Right now you read all of the sections and apply all that apply. Some are mutually exclusive, some aren't.
  • Figure out how to better say "YYYYMMDD%{scm}%{revision}" other things like that without giving someone the impression that those are actually RPM macros they should define, or that are already defined. I guess shell variable notation, maybe.

I could phrase it as a set of questions.

  1. Has upstream ever chosen a version?
    a. No: use "0".
    b. Yes:
    1. Check for invalid characters and munge
    2. Check for non-sorting version. Split into X and Y, use version X and "extra version information" Y.
  2. Prerelease, release or postrelease:
    a. Prerelease:
    1. use the version that upstream will release as Version:
    2. use "package release number" 0.N, N >= 1.
      b. Release:
    3. use the use "Package release number" N, N >= 1
  3. Snapshot?
    a. Yes: use YYYYMMDD.REV or YYYYMMDDSCMREV for "snapshot information".

But even then, there are still issues with ordering. And I really don't want to have to figure out how to make a flowchart. Maybe someone could offer a suggestion or two.

Metadata Update from @tibbs:
- Issue assigned to james

2 years ago

Metadata Update from @tibbs:
- Issue close_status updated to: None
- Issue tagged with: committee

2 years ago

I would like to bring this back up. I did make a few small tweaks since the last time we talked about this and I'm relatively satisfied with what's there now.

To recap, it's mainly a big reorg with functional changes limited to the following:

  • Explicit mention of the already approved use of Version: 0.
  • Allowing "YYYYMMDD.githash" in the "snapshot information" field.
  • Explicit mention of the case where upstream uses invalid characters.
  • More detailed explanation of dealing with "unsortable" elements. The original guidelines just said to move the "non-numeric" portion to the "extra version information" and then added an exception to the exception saying that non-numeric portions are OK if they're "properly ordered simple versions", which wasn't really defined.

Metadata Update from @tibbs:
- Issue untagged with: committee

2 years ago

Metadata Update from @tibbs:
- Issue tagged with: hasdraft, meeting

2 years ago

We discussed this at this weeks meeting (http://meetbot.fedoraproject.org/fedora-meeting-1/2017-02-23/fpc.2017-02-23-17.00.txt):

So as always, I'm completely open to comments. If you didn't vote, please give the page a read and let me know what you think. Two more votes and I can put this one behind me.

We discussed this at this weeks meeting (http://meetbot.fedoraproject.org/fedora-meeting-1/2017-03-02/fpc.2017-03-02-17.00.txt):

  • 678 Ban use of directory Requires (geppetto, 17:06:55)

  • LINK: https://pagure.io/packaging-committee/issue/678 (geppetto,
    17:07:07)
  • Mostly agree we can close it, but leave it open for a bit so
    ignatenkobrain can comment if he wants. (geppetto, 17:09:27)

Metadata Update from @james:
- Issue untagged with: hasdraft, meeting
- Issue tagged with: needinfo

2 years ago

Metadata Update from @james:
- Issue untagged with: needinfo
- Issue tagged with: hasdraft, writeup

2 years ago

Metadata Update from @james:
- Assignee reset

2 years ago

@james, that seems to be info on a different ticket. I'm pretty sure the final vote total for this ticket ended up at +6.

Written up. Announcement text:

The guidelines on versioning packages were completely rewritten in order to make them (hopefully) more comprehensible. This rewrite was not intended to introduce functional changes, but during the draft process, the following specific changes to the versioning scheme were approved by the committee and introduced:

  • Use of Version: 0 when upstream has not chosen a version.
  • Allowing "YYYYMMDD.commithash" (instead of requiring mention of the SCM in use) in the "snapshot information" field.
  • Explicit mention of the case where upstream uses invalid characters.
  • More detailed explanation of dealing with "unsortable" elements, instead of leaving many cases undefined.

The examples were also split out of this page and placed in a new page which is outside of the protected Packaging hierarchy. The rewrite of this page is not yet complete at this time, but I encourage everyone to help out.

@james, that seems to be info on a different ticket. I'm pretty sure the final vote total for this ticket ended up at +6.

Written up. Announcement text:

The guidelines on versioning packages were completely rewritten in order to make them (hopefully) more comprehensible. This rewrite was not intended to introduce functional changes, but during the draft process, the following specific changes to the versioning scheme were approved by the committee and introduced:

  • Use of Version: 0 when upstream has not chosen a version.
  • Allowing "YYYYMMDD.commithash" (instead of requiring mention of the SCM in use) in the "snapshot information" field.
  • Explicit mention of the case where upstream uses invalid characters.
  • More detailed explanation of dealing with "unsortable" elements, instead of leaving many cases undefined.

The examples were also split out of this page and placed in a new page which is outside of the protected Packaging hierarchy. The rewrite of this page is not yet complete at this time, but I encourage everyone to help out.

Metadata Update from @tibbs:
- Issue untagged with: hasdraft, writeup
- Issue tagged with: announce

2 years ago

Metadata Update from @tibbs:
- Issue untagged with: announce
- Issue close_status updated to: accepted
- Issue status updated to: Closed (was: Open)

2 years ago

Login to comment on this ticket.

Metadata