Versioning (SemVer vs. Dated)

[michael-hawker]

Why have we been calling it vNext? Especially, as currently, we're using version 8.0.0-beta.1 for these packages in our feed.

Currently, we follow Semantic Versioning. However, the Toolkit is made of a number of smaller and vastly different components, in the past whenever we'd make a new revision, all of these packages were simultaneously built, updated, and pushed to NuGet. Even if they didn't have any updates! This causes a lot of churn for folks to update to a package that is effectively identical, let alone confusing.

We could individually Semantic Version the packages, but that can lead to cases where one package appears to be many versions ahead of all the others, leading to questions around what's the 'latest' version of the Toolkit at a whole.

Recently, the Windows App SDK team themselves have adapted to using dates within their release numbers, see their version table here. Other projects with many smaller components use date based versioning as well, like FlatBuffers. We're leaning towards adopting some sort of similar practice for 'vNext' before we push packages to the central NuGet feed.

Let us know your thoughts on this decision and the versioning pattern we should use.

[Pdawg-bytes]

I think the current versioning scheme is better. Including a long date code in the name makes it sort of hard to read sometimes and overcomplicates things. If people want to know the release date, they can simply check the GitHub repo for changelog and time of release.

[itsWindows11]

I've been thinking of something like (major).(minor).(revision)-beta.(build number).ddmmyy for betas specifically with the package publishing date, so something like 8.0.0-beta.2.051023. Semantic versioning (i.e. just 8.0.0) could be kept for stable and should be the same across packages in my opinion.

[huynhsontung]

Do we even need to have a shared version number for the whole toolkit? I see the toolkit as a bundle of components that I can pick and choose. I think it makes sense for these components to have their own independent versioning.

When there is a major change to the whole toolkit, we can use the date to address it like Windows does (for example, Community Toolkit Fall 2024 Update). All the package versions will be bumped accordingly and the new versions will be noted in the release notes.

I'm quite fond of SemVer so I kinda want it to stay.

[michael-hawker]

Yeah, this is really the crux of the issue is that in the past, we bumped everything together, so a bunch of packages would update from 7.0 to 7.1, but contain no code changes and effectively be the same, so it's just leads to noise, randomization, and confusion for people to see an update that doesn't do anything.

So just really thinking about how we can just detect what code has changed and only push packages out that have changes.

The problem is if we want to make a breaking change in a single package and it's now 9.0 vs. the rest being 8.1 or something, then folks start asking if the others are outdated or when v9 is coming out, etc... leads to I think just as much confusion. We saw this when we split off the .NET Community Toolkit now approaching their 8.2 release and we've remained on 7.1. Though think folks are slowly getting to the point of them being separate projects now, but early on we had a lot of questions about 8.0 for the WCT.

This is where just basically using date based versioning only solves both of these issues. You only see an updated version when the package has an update (and you know how old it is). Plus, since there's not an explicit 'version number' related update that ties everything together, it's harder to be confused if things are just the latest version, you'll know based on the package version. And if it's old, you'll check or come investigate what's going on with it here.

We really see the main repo moving forward as the place for super-stable, tested, and reliable components. Any new work until it reaches that point is done in WCT Labs. We probably won't want to make a lot of breaking changes once things move here, but they've happened in the past.

There is the hybrid approach still too like the Windows App SDK team is doing now of like (major).(minor).yymmdd.(patch) too. But I'm still worried about if some packages are 9.0 and some are 10.3 what that does for discussing components vs. just releasing things as they get updated and revving a date.

Like maybe our 'releases' in the future are just us having fixed points in time where we can decided to bring X number of controls that are ready from Labs over to the Toolkit, get them together, and celebrate and announce what these new stable components are.

We're really thinking about how we change our processes and look forward to how we can easily maintain and ship updates to the Toolkit without getting tied to a ton of processes to release code.

[huynhsontung]

We saw this when we split off the .NET Community Toolkit now approaching their 8.2 release and we've remained on 7.1. Though think folks are slowly getting to the point of them being separate projects now, but early on we had a lot of questions about 8.0 for the WCT.

Maybe this was just a confusion during the migration process. I think it's reasonable for the toolkit to start treating these as separate packages in vNext. The toolkit can have a version matrix front and center in the project's main README to somewhat alleviate the confusion. I still think having an independent SemVer version for each package will be beneficial in the long run.

SemVer also has the advantage of knowing how big of a change from one version to the next whereas the dated version does not.

[bogdan-patraucean]

How about using the [major].[minor].[build].[date].[revision]

• [major] - for a major change, all packages will be updated
• [minor] - for changes that might affect more packages but those changes are not changing something major
• [build] - for changes of each package individually, when something needs to be fixed, or improved in one particular package
• [date] - for more clarity about how recent those packages were updated
• [revision] - as you said

Example:
8.1.3.232104.0
8.1.6.232004.0

Both of this packages share the same .NET version, they are part of some bigger change, and individually they might have some fixed and improvements, one being 3 while the other 6, the date specifing when the update occured.

What do you think?

[michael-hawker]

It's more a concern about the Major/Minor numbers over date of update (I mean that's in metadata anyway).

If we have one package on 12.5 and another on 8.4 what's the "current" version of the Toolkit? How do we communicate that? What constitutes a "release"?

If we move to a model where we're just rolling out updates on NuGet to packages as soon as we fix something (as everything is tested and vetted before merging), then "releases" could just become a point in time when we migrate component(s) that have reached maturity from Labs instead. So, does it make sense to assign a number to that, start them at 1.0 when everything else is 8+?

[bogdan-patraucean]

In my example there shouldn't be a case where we have 12.5 and 8.4, only one of them. If everything is 8+ then the next one will be 9 including those new released components from Labs.

[michael-hawker]

Thinking more on this, I think it's about if an individual component wants to make a breaking change, then with Semver, it'd want to go to '9' while every other component is at '8', otherwise it'd have to wait to make a change until we're at some cycle to make a major version rev. So if we want components to be able to break at any point it means they can just get inflated version numbers.

Otherwise, we need to coordinate any breaking changes across packages to do a larger version rev when we think we have some other breaking change.

[michael-hawker]

Last call for any input on this topic. I think this is the biggest open question remaining about the project versioning moving forward in this new space. And I'm still not sure which path we want to go down. Will put a call out in a couple of places to get some more eyes here and hopefully some more opinions.

[yoshiask]

I'd certainly prefer staying with semantic versioning. It makes it easier to talk about the Toolkit, including figuring out which version has the features you need and which versions are compatible with each other.

[kmgallahan]

I would prefer semver 2.0.0 rules be followed.

When a MAJOR release of the "main" WCT package updates (due to breaking changes), all smaller packages update MAJOR release as well since they (all?) have dependencies on the main/shared packages anyways (CommunityToolkit.WinUI / CommunityToolkit.Common).

MINOR and PATCH versions can then stray to follow the semver rules. To relieve confusion over the latest package versions semver metadata rules can be used for build dates. Nuget and GitHub readme's and perhaps even release notes can all display a short table indicating the latest package versions to ensure newcomers are aware of the system.

I'm not a fan of the WASDK breaking away from semver rules ~10 months ago.

[michael-hawker]

Ties into this discussion here too: #33 (reply in thread)

If an individual component needs to make a breaking change, then it's either not aligned with the rest of the packages OR it needs to hold that until we do a 'breaking' release.

So, it's either all the packages drift and are independently versioned (which can make it hard to know the base dependencies) or we have to hold certain changes until certain points in a release cycle.

I do like the major.minor.YYMMMDD.revision idea at least, where if we have to rev major/minor versions along with dependencies we can easily mark the related pieces, but then still increment a package as we need day-to-day or even multiple times a day with the revision.

Maybe like a happy medium?

Part of this whole change-over is to make it easier for us to release as we have our stable code-base. So it may just be that every few months we're doing updates to align to drops of WinUI, Uno, and .NET anyway.

[michael-hawker]

Forgot to circle back and close this discussion, we've got all our versioning sorted out in the last few PRs including #173

We can increment the major/minor for all packages together with properties in our root props file as well as any preview moniker, but for official releases we'll basically be following:

major.minor.YYMMDD

For preview releases we have the following setup:

• main builds will be appended with -build.<incremental_build_number>, signed, and then pushed to our MainLatest feed
• PRs will be appended with -pull-<pr#>.<_incremental_build_number> and pushed to our PullRequest feed so they're easy to identify
• and we can of course push to NuGet any '-preview' or other type releases as we've done as well.

This should hopefully strike a balance between us keeping versions of the toolkit packages aligned to various dependencies and updating our major/minor accordingly as well as easily releasing new versions and making them discoverable and current.

We discovered a lot of nuances when building the Toolkit (as we use the Toolkit to do so), so with package dependencies it's hard for us to just ship an individual update to a single package in many cases, this is still something we need to sort out moving forward to determine which packages may need to be updated so when a change occurs we can only push the packages which are required to be updated.