Version numbering for OS releases

[bgilbert]

🚨 🚨 🚨 bikeshed alert 🚨 🚨 🚨

We should figure out FCOS version numbering.

Some properties that could be useful:

• Version numbers that aren't too unwieldy
• Including the Fedora release on which the OS is based
• Distinguishing between new snapshots and updates to existing snapshots
• Distinguishing between releases on different streams
• Determining the age of a release from inspection

Proposal 1

<Fedora release>.<snapshot serial number>.<patch release>

• The first next snapshot of F31 would be 31.0.0.
• The first testing snapshot of F31 might be 31.4.0.
• If there were an out-of-cycle update to 31.4.0, it'd be 31.4.1.
• The first stable snapshot of F31 would then be 31.4.2.
• The next testing snapshot of F31 would be 31.5.0.

Advantages

• Clean, pronouncable version numbers
• Different snapshots have different minor versions

Disadvantages

• Not clear from inspection how old a version is
• Not clear from inspection what stream a version is from

Proposal 2

<Fedora release>.<snapshot YYYYMMDD>.<patch release>

• The first next snapshot of F31 would be e.g. 31.20191015.0.
• The first testing snapshot of F31 would be e.g. 31.20191216.0.
• If there were an out-of-cycle update to 31.20191216.0, it'd be 31.20191216.1.
• The first stable snapshot of F31 would then be 31.20191216.2.
• The next testing snapshot of F31 would be 31.20191230.2.

Advantages

• Different snapshots have different minor versions
• Clear from inspection how old a version is

Disadvantages

• Version numbers are harder to read
• Not clear from inspection what stream a version is from

Other thoughts

• CL-style days-since-epoch versioning strikes a balance between having pronounceable versions and indicating staleness, but doesn't do a great job of either one. The version numbers are somewhat unpredictable and unwieldy, and one needs to know the current core_date to determine how stale a release is.
• We could add a stream indication to the version number, such as a suffix letter. It seems like that would make the version more unwieldy.

[lucab]

I would not embed the full YYYYMMDD (as last-minute day-slips happen) but still keep some kind of coarse-grained timestamping. ostree-style YYYY-CNTR could be a good middle ground maybe?

We could add a stream indication to the version number, such as a suffix letter. It seems like that would make the version more unwieldy.

A short marker for this in the version ID would be welcome, for various reasons I find myself doing such manual lookup almost daily for CL.

Ref: streams definition is at https://github.com/coreos/fedora-coreos-tracker/blob/master/Design.md#release-streams

[dustymabe]

So today for Fedora Atomic Host we do <Fedora release>.<snapshot YYYYMMDD>.<daily rebuild #>. Basically we have granularity down to the day and then a number at the end for uniqueness on a given day. This format has worked well for us because it provides uniqueness, and a lot of information about the release.

For your proposal 2 <Fedora release>.<snapshot YYYYMMDD>.<patch release> I'm not sure exactly what <patch release> is needed for. If we do a build on monday and we need to rebuild on tuesday to fix something then why not bump the <snapshot YYYYMMDD> to tuesday?

[dustymabe]

I would not embed the full YYYYMMDD (as last-minute day-slips happen) but still keep some kind of coarse-grained timestamping. ostree-style YYYY-CNTR could be a good middle ground maybe?

I like the fine grained time stamping, but compromise is key. If we compromise I'd prefer something like YYMM.CNTR. So 1811.20 would be November 2018 and the 20th build of the month. This has the benefit of giving you the month at least over the YYYY-CNTR approach.

[bgilbert]

If we do a build on monday and we need to rebuild on tuesday to fix something then why not bump the <snapshot YYYYMMDD> to tuesday?

It seems important to distinguish between a release which is a new snapshot (and thus might break something) and a release which is a bugfix backport to an existing snapshot (and thus hopefully will not). Also, the age of the software in the release is fundamentally tied to the age of the snapshot, so the distinction seems even more relevant if a date is included in the version.

[MureDanta]

I'm not sure if this discussion is still ongoing, but given how frequently FCOS will update, as a user I prefer something like Proposal 2, with the full date and the patch level. The less-fine-grained YYMM-CNTR approach seems to hide the date for reasons that are not clear. If the full YYYYMMDD is used, people will instantly recognize it for what it is, and given that FCOS is expected (at least for now) to update every two weeks, it means that, at a glance, you'll be able to tell exactly how old your OS is, how soon to expect an update, etc. From a troubleshooting point of view, that ability seems useful to me. The date in the UTC timezone would be best, or at least less prone to weirdness.

[lucab]

Side note: whatever numbering format we pick, we must ensure that it satisfies the linear order property across all labeled releases.

This is because the set of available updates we get from cincinnati is not implicitly ordered. Client will have to order them in some consistent way, in order to avoid flapping and staging multiple available updates back and forth.

[steveej]

@lucab

Side note: whatever numbering format we pick, we must ensure that it satisfies the linear order property across all labeled releases.

This is because the set of available updates we get from cincinnati is not implicitly ordered. Client will have to order them in some consistent way, in order to avoid flapping and staging multiple available updates back and forth.

I don't think that's necessary. The client only has to identify their current release, and can then use the edges to traverse to the next version. The edges are ultimately defined in your release-metadata, and they're not treated and ordered as versions anywhere on the Cincinnati side.

[jlebon]

Not clear from inspection what stream a version is from

On this point, one thing we brought up in discussions today was that rpm-ostree/ostree itself has no qualms about having multiple version strings sitting on the same branch. Having non-stream-specific information somehow in the version string also means that the same version string could end up being re-used across the separate streams, which might lead to confusion.

[lucab]

Related to the last comment: coreos/zincati#25

[dustymabe]

Now that we are closer to preview let's make some progress on this topic. In #81 (comment) I mentioned another option. I'll formalize it here:

Proposal 3

<Fedora release>.<snapshot YYYYMMDD>.<daily build counter>

• The first build of F31 today would be e.g. 31.20190626.0
• The second build of F31 today would be e.g. 31.20190626.1
• The first build of F31 tomorrow would be e.g. 31.20190627.0

We don't worry about conveying 'snapshot' information in the version number.

@bgilbert
It seems important to distinguish between a release which is a new snapshot (and thus might break something) and a release which is a bugfix backport to an existing snapshot (and thus hopefully will not). Also, the age of the software in the release is fundamentally tied to the age of the snapshot, so the distinction seems even more relevant if a date is included in the version.

I'm not sure how valuable that information is to the user who is doing auto updates. It might be useful for us, but we also know which build had what fixes in it and why it was built. I guess you can make that same argument about dates in the version name.

One thing to ask is when comparing proposal 2 to proposal 3, is the added complexity to generate the version based on the snapshot worth it?

[jlebon]

Any thoughts about #81 (comment)? Do we want to include stream information somehow in the version?

I'm not sure how valuable that information is to the user who is doing auto updates

Note if we do this (proposal 3), we can end up in a situation where the stable version date is higher than the testing version. Which could be confusing for users when staring at the download page and choosing which stream to download. Proposal 2 has the property that stable < testing < next always holds.

[dustymabe]

Any thoughts about #81 (comment)? Do we want to include stream information somehow in the version?

It wouldn't bother me to add a +streamname or something like that, but I know some people get weird when version strings get too long. Would you like to throw out another proposal?

Note if we do this (proposal 3), we can end up in a situation where the stable version date is higher than the testing version. Which could be confusing for users when staring at the download page and choosing which stream to download. Proposal 2 has the property that stable < testing < next always holds.

I'm not sure.. I would typically think we'd sync from testing to stable to do a release and then update testing with testing-devel (like water flowing down). Which would typically mean they be chronological or on the same day. They could get out of chronological order if we do a backport to stable and not testing, but I don't think it matters too much if they do.

[jlebon]

They could get out of chronological order if we do a backport to stable and not testing

Right, that's the situation I'm talking about. :)

I also like what @MureDanta said in #81 (comment); resetting the timestamp on respins drops some of those benefits.

One thing to ask is when comparing proposal 2 to proposal 3, is the added complexity to generate the version based on the snapshot worth it?

Yeah, that's a good point. It's almost like if it'd have to be part of the config itself, so it naturally flows down the streams? Actually, we already know that for the multi-arch issue, we'll need something external driving versioning. I don't think it would be too hard for it to also figure out whether this is a patch release or a new build, based e.g. on a BASE_VERSION file in the config or a timestamp in the lockfile or something.

I like proposals 2 and 3 the most I think. And really since they're the same format, we could even start with 3 (which is easier to implement) and then move to 2 later on.

[dustymabe]

I also like what @MureDanta said in #81 (comment); resetting the timestamp on respins drops some of those benefits.

yeah I mostly interpretted his statement as saying he likes the extra granularity in the date, but I see what you're saying.

Yeah, that's a good point. It's almost like if it'd have to be part of the config itself, so it naturally flows down the streams? Actually, we already know that for the multi-arch issue, we'll need something external driving versioning. I don't think it would be too hard for it to also figure out whether this is a patch release or a new build, based e.g. on a BASE_VERSION file in the config or a timestamp in the lockfile or something.

Yeah I guess we could manually update it in the configs for testing and stable when we do the "merge" from testing-devel to testing and testing to stable

I like proposals 2 and 3 the most I think. And really since they're the same format, we could even start with 3 (which is easier to implement) and then move to 2 later on.

Sounds good. I guess let's go with Proposal 2, but initially implement Proposal 3 just to go ahead and get something out.

[dustymabe]

Please vote via 👍 👎

Proposed: Initially implement Proposal 3 until we can get tooling in place to implement Proposal 2. They are the same format so moving from one to the other won't require any migration.

[lucab]

For both P3 and P2, do we a point in the pipeline where we can pick the stream label and derive a short marker from it? I'm asking about something like stable -> S30 to address #81 (comment).
If it is unfeasible or too unwieldy, I'm fine if we agree to defer that to a human lookup in a webpage (but less than optimal).

[dustymabe]

@lucab we didn't quite flesh it all out but I did make this comment in #81 (comment)

• It wouldn't bother me to add a +streamname or something like that

Since we've got some resolution on initial formatting in this ticket and the stream indicator can be added, let's separate the discussion into a new ticket: #211

[bgilbert]

PR in #298.