What software versioning convention should be adopted for GitHub releases?

[bryce-carson]

CalVer sounds really good especially as we will have to do changes and releases based on external factors i.e. if a security issue is found in a package we need to push a stable release immediately and if we work on a bigger feature i.e. porting our aged core to rust and using it to do the heavy lifting and by that reduce the complexity we have sitting in our chaotic elisp core we may not have much to show for weeks.

If we go for CalVer I would vote for YYYY.MINOR.MICRO this would allow us to increase micro for bug fixes and minor for breaking changes, resetting each year. A year change is then always like a breaking change.

What do you think?

Originally posted by @smile13241324 in #16775 (comment)

There are numerous semantics we could adopt, but I think for something as significant as an elisp to rust transition for core/ should be done in spacemacs/core-rs and populated as a submodule during install. If core/ is a submodule users can choose to populate it with either the default elisp, which should be maintained in perpetuity for hacker's sake, or the rust port for speed (when released).

I think whatever semantics are adopted should respect:

• layer api
• dotspacemacs version
• patches
• features?

The big question is breaking changes for who? Package authors? Layer authors? dotspacemacsen? That's what a version number should encode. The meaningful bits at a glance. Is it safe to update from 2512–2601 in a scheme with YYMM as a prefix?

YYMM.LDPPP

• year
• month

and

• layer
• dotspacemacs version
• patch

1. 2506.1.1‐001
2. 2506.1.1‐002
3. 2507.1.1-001
4. elided
5. 2509.201003

They're all directly comparable with < if each larger component resets the others, just like a clock, yes.

Maybe the usual bits should be flipped? Or CalVer is crap for us? 🤷 Are version numbers helpful at all?

[bryce-carson]

For CalVer, at least, there are release cycles and maintenance periods.

Ubuntu maintains LTS for some years, and interim releases for less time.

Their YY.MM prefix encodes release dates, and indicates when service will end.

What would be meaningful for us? Certainly, the same semantics don't apply.

25.09 might be a release we support only until it is replaced, so what matters isn't the date of the release or when the support period starts. 25.09-2045 to 25.10 could be safe, but the YY.MM doesn't indicate that.

What does stable mean to us?

[bryce-carson]

User Journey

The ideal user is curious and willing to read. Let's call this user Doubting Thomas. Who is Thomas? Thomas: he is curious and reads voraciously. He trusts brands and upstream releases, rather than middlemen and redistributors like the Windows Store; he once had a bad experience with software released through a software store and swore against using them, so he obtains software from vendors directly rather than redistributors.

Thomas would like to know if it is safe to update from one release of Spacemacs to another. The following paragraphs interrogate aspects of his thought process.

Assuming the DELPA proposal in #16775 is merged, Thomas knows that updating to the next release will (hopefully) have minimal security concerns.

Thomas reads CHANGELOG.org on the Spacemacs website, because he's the type of person who acquires Spacemacs from there and reads documentation there. While reading this file he sees that nothing in the "Breaking Changes/Major" heading impacts him: his version of Emacs is the latest release. He notices a favourite layer of his is included in the "Breaking Changes/Layers" section. He consults the offending subsection; how worrisome for him!

Keybinds were reorganized. He doesn't have keys committed to muscle memory and always reads the prompts which key provides, so he looks at the next change notices for his favourite layer.

A broken keybinding was fixed.

Support for a third-party utility program he doesn't use was moved to another layer because his favourite layer manages configuration of a programming language no longer supported by this third party utility.

He decides to update.

Why examine this user journey?

Knowing where particular types of users (personas) will encounter issues during the update procedure will help us consider whether some given culture of software version labelling will help users decide to update.

In short, software version labelling offers an alternate encoding of things like utility, quality, and recency. Do we, as contributors and maintainers, want to communicate these sorts of things through some culture of software version labelling?

I believe we shouldn't, especially if we are merely deleting the master branch and then making a release on GitHub once we identify a future or past commit which we believe is "stable".

Using CalVer in this scenario would be appropriate. Some number with two then five as the most significant digits (representing twenty-five of the current year in the Gregorian calendar) and then a string of other digits could encode whatever we like, as long as we're consistent then < is sufficient to compare version numbers in elisp or other languages and shouldn't be problematic in git tags.

Why the fuss over this?

• Users think 0.13--0.14 is a smaller change than 13.7--14.0, despite these numbers having non-ordinal semantics (they don't occur in a regular series).
• Encoding some types of information in these numbers is optional for software teams, other types of information are required (see: git).

There are likely other good reasons.

[davidpiano]

I don't think the user journey of "Thomas" outlined above should be a significant focus. "Thomas" is taking care to follow protocol and act responsibly, and because of that, he is likely to create a decent outcome for himself with almost any versioning system that isn't obviously ridiculous.

Two much more important user journeys are those of "Oscar" who is disorganized and a little negligent, and "Sid" who always tries the things that are not recommended.

[bryce-carson]

Two much more important user journeys are those of "Oscar" who is disorganized and a little negligent, and "Sid" who always tries the things that are not recommended.

I agree! Let's create these. When I have time I'll try my hand at one or the other. Maybe ChatGPT would be better at being illogical than me.