Repository navigation
RFC: Version nightly builds by the next release rather than previous. #12127
Description
Activity
FWIW this kind of "forward version" numbering is exactly the ethos behind my
git-versionertool, 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.pyThat 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.dfuAlso, 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.
Reacted by FilipSLOI'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.
Reacted by FilipSLOI'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?
@robert-hh Damien tells me this is fixed and new builds should start appearing soon.
Reacted by Andy PiperThe 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
deflatemodule) says "Added in MicroPython v1.21", but if you download a nightly (which does include the deflate module) the file hasv1.20in its name.+1 in favour of
forward-versioningand maybe a plus name to identify that still in progress (not released yet), like asrelease_candidateReasons in my opinion:
- Using just
unstablewill be confused on the forums and discussions as already pointed. - Removing the
version namewill 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 buildswithforward-versioningwill be easy to understand, and everything will be simpler in my opinion
- Using just
Honest question: if you tell someone x has been added in
v1.21 nightlythen 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.
Reacted by Peter HinchTo 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.dfumeans 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.dfuwhich I think is a good solution and sort of automatically reads 'the 327th preview build for next release v1.21'.
Reacted by Peter Hinch and Damien GeorgeI 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.dfuthen the welcome banner on the device saysMicroPython v1.20.0-394-g326dfd2a8. I am proposing that we should change this such that the equivalent file would bePYBV11-20230823-v1.21.0-preview.394.g326dfd2a8.dfuand the welcome banner would sayMicroPython 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 ispreview.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).Reacted by David Lechner, Matt Trentini and Damien GeorgeThe 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.
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.versionand 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. >>>- added a commit that references this issue
on Oct 22, 2023 - added a commit that references this issue
on May 23, 2026 - added a commit that references this issue
on Sep 21, 2026
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.hetc immediately to the next version after git tagging a release.Inspired by #12108 (comment)