FYI: New versioning scheme for preview (formerly nightly/unstable) builds

[jimmo]

In addition to the release firmware, the MicroPython project publishes automatic builds of the current latest codebase. Until now we've called these "nightly" (on the downloads page) or "unstable" builds (in the filename). Neither of these words accurately convey what they are -- they aren't built nightly (triggered automatically on push) and we have no expectation that they are unstable (we run the full CI). Also we're currently working on adding hardware-in-the-loop CI testing to do the same hardware testing that we currently do on the releases.

But the main source of confusion was that we versioned these builds with the previous release name. i.e. after releasing v1.20.0, there were "nightly" builds named v1.20.0 up until we released v1.21.0. But these builds aren't really v1.20.0, they're the in-progress version of v1.21.0, e.g. new documentation describing a feature added in v1.21.0 applies to them.

So to address both of these issues, as of today's v1.21.0 release, we are going to refer to these builds as "preview" builds, and version them with the next release. i.e. the first preview build will be v1.22.0-preview.0.gHASH, followed by v1.22.0-preview.1.gHASH, etc.

This will also apply to local builds (both from the source tarball and git repo). If you build at the v1.21.0 tag, you'll see v1.21.0, but anything past that will show 1.22.0-preview.N.gHASH in the version info.

See #12581 for the changes, and #12127 for more background.

[jimmo]

(The firmware build server is currently running the v1.21.0 release build, and shortly after that the preview builds will start showing up. Please let us know if you see any issues!)

[robhamerling]

Minor issues:

In initial text third paragraph last line: "followed by 1.22.0-1.gHASH" is missing 'preview."

Current source shows git-tag v1.21.0-2-g523284777. But after building firmware from it the command prompt shows v1.22.0-preview.1.g523284777. From where comes the one preview number difference?

[glenn20]

tools/autobuild/autobuild.sh uses git describe --tags --dirty --always --match 'v[1-9].*', which returns v1.22.0-preview-1-g523284777. The --tags options causes it to match the non-annotated tag applied to 69e34b6b6bd (see git log). autobuild.sh does some further mangling to replace the last two '-' with '.' in $FW_TAG.

[robhamerling]

Thanks, I'm afraid my experience with git is limited!
With your 'annotated' describe the numbers is the git-tag and command prompt do match.
Leaves only a difference between hyphens or full stops as in Jimmos original message.

[jimmo]

In initial text third paragraph last line: "followed by 1.22.0-1.gHASH" is missing 'preview."

Thanks! Fixed.

@robhamerling As to your second question, it's a bit subtle (because it's different to how it used to work where the N counted since the release), but git describe is returning the number of commits since the last tag. The release is tagged as v1.21.0, then the first commit after that is tagged as v1.22.0-preview. So the N is number of commits since the preview tag. Hence the first commit is actually the zeroth commit, whereas previously the release commit would have been the zeroth.

[robhamerling]

@jimmo: I probably understand the numbering now, thanks.
Still a remark: I see some inconsistency in the naming: use of '-' (hyphen) or '.' (dot) between parts of the name:
the git-tag v1.22.0-preview-3-ga06f4c8df
firmware files: v1.22.0-preview.3.ga06f4c8df

[jimmo]

the git-tag v1.22.0-preview-3-ga06f4c8df

This is not the git tag, this is the output of git describe. The tag is just v1.22.0-preview.

firmware files: v1.22.0-preview.3.ga06f4c8df

This is the version in "semantic versioning" format (semver), which is made up of MAJOR.MINOR.PATCH-PRERELEASE. Our prerelease component is made up of three dot-separated identifiers preview, N, gHASH. See https://semver.org/#spec-item-9 and also https://semver.org/#spec-item-11 for why we dot-separate them.

The confusion here is likely that the semver-compatible format is very close to but different to what git describe generates. However, the git describe output is not used anywhere (in firmware, documentation, etc), we parse it to generate the semver format.