Review and analyze well-known versioning practices

[Arlodotexe]

Background

Raised by Lamparter in the Windows App Community Discord.

Problem

The new SDK and Server Companion codebases are still nascent and aren't yet ready to publish. Before we publish, we need to determine what practices we want to use for versioning anything we publish or release.

Solution

Review and analyze the well-known options. They each have different rationale and dynamics, and weigh with different pros and cons. We should fully lay out and analyze at least this much to see what would be best for our purposes.

Defining well-known options

SemVer2.0 w/ Standard Prerelease Extension

Old reliable. Documented at https://semver.org/, it works as follows:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backward compatible manner
3. PATCH version when you make backward compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

The last line, "labels for pre-release and build metadata [...] as an extension to the [...] format.", is referring to versions such as 1.0.0-preview1, 2.0.0-experimental2, and so on.

SemVer2.0 w/ OwlCore prerelease extension

Instead of using the standard x.x.x-label extension for prelease, my own OwlCore libraries use a different, custom extension that could be worth consideration as well.

Libraries that are still in the "initial incubation" development stage are always MAJOR versioned below 1, with MINOR versions marking breaking changes and incompatible API changes.

The goal here for any good software developer, then, is to minimize the number of minor updates that are "breaking" before you reach something you feel you can call "stable".

In contrast to the standard prerelease extension to semver2.0, this encourages openly practicing planning ahead, testing, and rapidly iterating during your initial development phase. This is an important skill to cultivate at a manageable pace, as collaboration with others is a natural incentive to minimize breaking changes, which removes barriers for further collaboration.

This setup is designed to create a more intuitive way to manage pace, compared to the standard prerelease extension.

SemVer2.0 w/ Windows Community Toolkit extension

The versioning used by the Windows Community Toolkit and Windows Community Toolkit Labs have some unique properties that make them worth considering.

In both repos:

• The PATCH version is the date in YYMMDD format.
• The MAJOR and MINOR version is hardcoded at the repo level via Build.Directory.props
  • In Labs, MAJOR is 0 and MINOR is 1. This never changes.
  • In WCT mainline, MAJOR is 8 and MINOR is 2. This may change based on release cycles.
• For Labs, a unique build number is appended using the standard prerelease extension. Used to enabled multiple releases in a day.

Comparing and analyzing available options

SemVer2.0 w/ Standard Prerelease Extension

Pros:

• Established standard: Familiar to most developers, making it easy for new contributors or external collaborators to understand.
• Clarity of release type: MAJOR, MINOR, and PATCH changes are explicit and easy to track.

Cons:

• Rigid for early development: In early “incubation” stages, you might feel forced to release many breaking changes as new MAJOR versions, which can feel like overkill.
• Learning curve for custom labeling: If you need complex pre-release tags, it can get messy or inconsistent unless carefully enforced.

SemVer2.0 w/ OwlCore Prerelease Extension

Pros:

• Encourages planning & discipline: Breaking changes force a MINOR increment (while still under 1.0.0), motivating teams to be thoughtful before moving to 1.0.0 “stable.”
• Predictable iteration flow: By associating “0.x” with experimental/breaking changes, consumers know to expect churn until reaching 1.0.0.
• Flexible labeling: You can still attach labels like 0.5.0-preview1 or 0.5.0-beta1 for finer-grained distinction.

Cons:

• Requires consistent discipline: Teams must clearly communicate changes in each MINOR version.
• Marketing/optics: Some teams feel uneasy staying below 1.0.0 for too long, as it can signal “unfinished” to outsiders.

SemVer2.0 w/ Windows Community Toolkit Extension

Pros:

• Clear snapshot of build date: Seeing YYMMDD instantly tells you when the build was created, useful for quickly identifying recency.
• Easy build management: Teams can push multiple builds per day without confusion, thanks to incrementing the date and (optionally) a prerelease label.
• Predictable numbering logic: Contributors don’t have to think deeply about version increments. Just update the date.

Cons:

• Less direct meaning for non-Toolkit teams: Encoding the date in PATCH can be non-intuitive if you expect “PATCH” to represent minor bug fixes.
• MAJOR/MINOR less frequently updated: If you rarely change the first two digits, you might lose immediate clarity about how large or small a change is.
• Labs: need a plan for truly incompatible changes: Because the MAJOR and MINOR version numbers are pinned, you might not be able to signal a “big break” at all.

Choosing what works best

Ultimately, no single system is “the right” answer. It depends on how your team works, the rate of development, and how you want to communicate stability.

• For an early-stage library, OwlCore’s approach can encourage disciplined iteration without bumping to 1.0.0 prematurely.
• For production or widely-used projects, standard SemVer2.0 is more widely recognized.
• If frequent builds and clear dating are paramount, the Toolkit approach may be best.

I'm thinking that a reasonable strategy could be to adopt the OwlCore approach until we reach a stable version, then adopt standard semver2.0 or the Toolkit variant of semver2.0.

Let's Discuss

The options are fully laid out, and each bring something different to the table. What do we think we should do?