Skip to content

Instantly share code, notes, and snippets.

@brandonbloom
Last active July 19, 2025 05:44
Show Gist options
  • Select an option

  • Save brandonbloom/465625acaf0120354614e7fc0c117c62 to your computer and use it in GitHub Desktop.

Select an option

Save brandonbloom/465625acaf0120354614e7fc0c117c62 to your computer and use it in GitHub Desktop.

Versioning

This project uses $SOME_CUTE_VERSIONING_SCHEME_NAME. It works like this:

Version numbers have the short form:

<major>.<minor>

Stability

Functionality can be either stable or unstable. Stable features are not subject to breaking changes, even in major version upgrades.

Unstable features fall in to four categories: alpha, beta, deprecated, and internal.

Alpha features are subject to breaking changes at anytime and without warning.

Beta features may experience breaking changes, but the goal is for them to stabilize, and so such breakage will be accompanied by guidance.

Deprecated features will be removed in the next major version release. Warning and a migration plan will be provided.

Internal features are also subject to breaking changes at anytime. They differ from alpha features in that they are not expected to stabilize.

Version Numbering

When the major version is 0, it is called the "alpha release". All features are considered alpha, unless explicitly declared otherwise. Even if designated stable, functionality in an alpha release should should be treated as beta at best.

For major version 1 and up, all documented features are considered stable, unless otherwise indicated. All undocumented functionality is considered internal.

@paulapatience
Copy link
Copy Markdown

This versioning scheme is compelling. In particular, it codifies a more fine-grained measure of stability than semantic versioning does, with stronger assurances made for stable features. Semantic versioning could be seen as this versioning scheme with at most all features being declared beta plus a questionably useful patch version.

However, the specification is lacking some guidance in how to bump the major and minor versions. Suppose the major version is 1 or greater, so that some features are stable. Clearly these features will never undergo breaking changes. Also clearly is that deprecated features can be removed only when bumping the major version. But what is unclear is which features can be marked deprecated. Beta features would make the most sense, since the specification states that any breakage of beta features will be accompanied by guidance (which currently means, incidentally and not necessarily inconveniently, that any features designated stable during major version 0 can be removed only in major version 1).

So the major version is bumped when removing deprecated features. Should it be bumped in other situations, perhaps when making (any kind, or just large?) breaking changes to beta features? And what about minor versions? Bumped when making any other kinds of changes, including breaking changes to alpha and internal features?

Also, no mention is made about bugfixes possibly causing irremediably subjectively breaking changes in stable features. Presumably the intention is to allow bugs to be fixed, with some consideration for how breaking they are.

(For what it's worth, I like kngl's suggestion of StableVer as name for this scheme.)

@brandonbloom
Copy link
Copy Markdown
Author

Thanks for the feedback! I've made some changes.

@brandonbloom
Copy link
Copy Markdown
Author

Moved to a repository here: https://github.com/brandonbloom/StableVer/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment