RFC: Version nightly builds by the next release rather than previous.

Currently the nightly/unstable builds are named <board id>-<date>-unstable-<last release>-<commits since last release>-g<git hash>. e.g. pybv11-20230727-unstable-v1.20.0-327-gd14ddcbdb.dfu

(Compare to release builds, e.g. pybv11-20230426-v1.20.0.dfu)

I would argue that the nightlies have more in common with the next release than they do with the current release (especially later in the release cycle).

Should we consider changing the release in the unstable filename to be the name of the next release. This would mean that we change py/mpconfig.h etc immediately to the next version after git tagging a release.

Inspired by #12108 (comment)

FWIW this kind of "forward version" numbering is exactly the ethos behind my git-versioner tool, to automatically generate a version number that matches the next release. The end goal being that any master/main branch build can be the release artifact; tagging becomes an automated operation that applies the exact same version number it's already built with.

I already use this tool as part of the micropython build process for in-house project builds, it's fairly easy to integrate into
makeversionhdr.py

That being said, for the purposed of micropython I'm sure you'd want the logic squashed directly into this file to avoid any external dependencies... here's some I prepared a few years ago in anticipation of this issue ;-)

I'd personally prefer to see the version number removed from the filename. And 'unstable' replaced with 'nightly'. So:

<board id>-<date>-nightly-g<git hash>. e.g. pybv11-20230727-nightly-gd14ddcbdb.dfu

Also, while the number of commits since last tag is somewhat convenient, the hash always allows us to determine the specific version. The reason for dropping the version is for clarity and ease of support - when users describe the version they're using they can't explain it incorrectly.

I'd personally prefer to see the version number removed from the filename. And 'unstable' replaced with 'nightly'

+1 for something this, because it removes any possible ambiguity as to what version it is. If we're currently at 1.19 then nightly isn't 1.20 (except the very last night perhaps), nor is it 1.19 (except the very first night perhaps).

If not that, I'd go for the usual 'increment build or qfe number' which is actually quite clear as well: 1.19.0.100 (or 1.19.100 if you want) means '1.19 plus 100 nightly builds further'.

Basically as long as the exact same version number a release has or will have isn't in there, it should be more clear than it is now.

@mattytrentini

I'm in favour of either forward-versioning, and/or @mattytrentini suggestion of removing the version number.

Out of interest, is this issue related to the fact that I'm only seeing nightlies listed on the downloads pages up until July 27?

@dpgeorge

Out of interest, is this issue related to the fact that I'm only seeing nightlies listed on the downloads pages up until July 27?

@dpgeorge

@robert-hh

@robert-hh Damien tells me this is fixed and new builds should start appearing soon.

The word "unstable" has caused confusion in the forum/discussions.

The word "unstable" has caused confusion in the forum/discussions.

Yes, that's a good point. Also that the page says "nightly builds" but just the filename says "unstable". I think we should rename the files.

This just came up in discord, the context being that the documentation (e.g. for the new deflate module) says "Added in MicroPython v1.21", but if you download a nightly (which does include the deflate module) the file has v1.20 in its name.

+1 in favour of forward-versioning and maybe a plus name to identify that still in progress (not released yet), like as release_candidate

Reasons in my opinion:

Using just unstable will be confused on the forums and discussions as already pointed.
Removing the version name will be cause confusing too, because you do not know in what version that feature will be released.
All new docs (of the new features) will be correct for the new version. Example of deflate: the docs is correct "Added in MicroPython v1.21" but the nightly builds firmware still 1.20.
If all new features merged (and docs added) automatically will be released in the next version, if we use nightly builds with forward-versioning will be easy to understand, and everything will be simpler in my opinion

Honest question: if you tell someone x has been added in v1.21 nightly then are they supposed to know that v1.21 is yet unreleased, and nightly means it is actually v1.20 with a bunch of changes and a nightly build thereof? As opposed to, in my view much more logical, it being a nightly build of released v1.21?

Then semver (v1.20.133) at least does convey much more clearly what the state is, and the mismatch with the documentation seems like a minor point.

@jimmo

To clarify the above and after some discussion with @jimmo : my main point is that when using forward versioning, words like 'nightly' or 'unstable' do not clearly and unambiguously convey the information that if the current version is v1.20, then something like pybv11-20230727-nightly-v1.21-133-gd14ddcbdb.dfu means that v1.21 is the next version.

There are other commonly used terms in other software which don't have that problem though: 'preview' or 'candidate'. Combined with reordering a bit for readability this would come down to

<board id>-<date>-<next release>-preview-<commits since last release>-g<git hash>

e.g.

pybv11-20230727-v1.21.0-preview-327-gd14ddcbdb.dfu

which I think is a good solution and sort of automatically reads 'the 327th preview build for next release v1.21'.

@stinos

I definitely agree on "preview" as a much better alternative to "unstable" (or "nightly"), and goes a long way to resolving the ambiguity that @stinos and @peterhinch are highlighting.

An additional point from discussion with @stinos -- doing forward versioning is in-line with the semver specification, by using the "pre release" part. See item 9: https://semver.org/#spec-item-9

So v1.21.0-preview.N.gH (where N is the commits since last release, and H is the git hash) would be a "semver compatible" way of saying that this is a preview (nightly) build that is not yet v1.21.0.

Currently if I flash PYBV11-20230823-unstable-v1.20.0-394-g326dfd2a8.dfu then the welcome banner on the device says MicroPython v1.20.0-394-g326dfd2a8. I am proposing that we should change this such that the equivalent file would be PYBV11-20230823-v1.21.0-preview.394.g326dfd2a8.dfu and the welcome banner would say MicroPython v1.21.0-preview.394.g326dfd2a8.

(Note that in the initial post I focused on the download filename, but one of the main sources of confusion is that currently the welcome banner does not clearly indicate that it's a unstable/nightly/preview version, unless you know that the -N-gH scheme implies nightly... which I don't think is a reasonable thing to expect people to know).

In other words, my proposal is that the filename should be <BOARD><-VARIANT>-<DATE>-v<SEMVER>.ext, and the "pre-release" component of the semver is preview.N.gH. We could also use the "build metadata" part of semver, but importantly semver considers two builds with different build metadata to be ignored when determining version precedence, so I don't think it's appropriate here.

@mattytrentini With respect to the suggestions above about removing the version from the filename... would this also mean we should remove the version from the welcome banner (and sys.version). If not, what should that show? If yes, this feels to me like it would be even more confusing for users who are trying to align to what the documentation says.

The other reason to keep all three (version, number of commits, and hash) rather than just hash is that the welcome banner (and sys.version) should be consistent with what you get when you build from source. In which case the commit hash might not be meaningful, but version+number gives at least an approximate idea. (To be clear, I'm mostly talking about when people raise bug reports etc, and we ask for this information).

The version number must be there to tell, for what the preview is. Otherwise people could not tell the difference between a preview for 1.21 or e.g. 1.16 if both were built at the same date.

@jimmo

@jimmo my main reason for dropping the version was to support the use of the word nightly, consistently. It doesn't make sense to have a nightly v1.21 IMO.

But a better solution is to use a different word. The suggestion by @stinos - with added detail by you - is better, I think. +1 from me!

@jimmo

I agree with the general consensus of this discussion, and what @jimmo has summarised just above, which would be:

bump the version right after a release
change the version to append -preview.N.gH

And I think it's important to have the same thing in the following three places:

sys.version
the REPL banner
the filename when downloading firmware from the downloads page

One minor extra thing: should we drop the "v" prefix on the version in sys.version and the REPL banner? That would match CPython, which does eg:

$ python
Python 3.11.3 (main, Jun  5 2023, 09:32:32) [GCC 13.1.1 20230429] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

See PR #12127 for an implementation of this.

I haven't included the change to drop the "v" prefix because this flows onto many things, including the documentation.

Merge tag 'v1.21.0' into moat

all: Switch to new preview build versioning scheme.

Navigation Menu

Repository navigation

RFC: Version nightly builds by the next release rather than previous. #12127

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

RFC: Version nightly builds by the next release rather than previous. #12127

Description

Activity

andrewleech commented on Jul 31, 2023

mattytrentini commented on Jul 31, 2023

stinos commented on Jul 31, 2023

andypiper commented on Aug 13, 2023

robert-hh commented on Aug 15, 2023

jimmo commented on Aug 15, 2023

peterhinch commented on Aug 16, 2023

jimmo commented on Aug 16, 2023

jimmo commented on Aug 24, 2023

beyonlo commented on Aug 24, 2023

stinos commented on Aug 24, 2023

stinos commented on Aug 24, 2023

jimmo commented on Aug 24, 2023

robert-hh commented on Aug 24, 2023

mattytrentini commented on Aug 26, 2023

dpgeorge commented on Aug 28, 2023

jimmo commented on Oct 4, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions