uSync versioning versus Umbraco versioning

[KevinJump]

Versioning is something we have stuggled with for quite a long time now.

Independent versioning

Pre version eight of Umbraco we use to have our own version number - so we have uSync v1 - v4 supporting different versions of Umbraco v4.5 through to v7.15.x. While this was alright it was confusing for people to know exactly what version of uSync worked with what version of Umbraco.

v8/v9 version parity

For Umbraco v8/v9- we decided to sync the version of uSync - so uSync v8.x works with Umbraco v8 and v9 works with Umbraco v9.

v8 Exact Matching

For Umbraco v8 we initially followed this exactly so When Umbraco released a new feature in v8.4 we bumped the next version of uSync to v8.4 this has a few advantages and issues:

Advantages:

• Users could see exactly what version of uSync they needed to run for a version of Umbraco
• It was clear that we had version parity (less does uSync work with Umbraco v8.x questions)

Disadvantages

• we bumped minor version numbers when we need to.
• later versions where still backwards compatible, but that wasn't always obvious (e.g uSync v8.10 does work with Umbraco v8.0.x)
• We sometimes ran out of headroom if we made a 'breaking' change we couldn't bump the minor version number if that version of Umbraco wasn't out yet.

v8/v9 Major version match , minor independent

At around Umbraco v8.4 we decided that sticking with the exact version was to restrictive, so we let the minor version of Umbraco side out. as such uSync is now at v8.11.0 while Umbraco is at v8.18.0.

Our rule now is we update minor if we introduce new features / change the file format, we still try not to make breaking changes so the major version is ok.

Umbraco's new Release Schedule

With the move to dotnet core Umbraco's release schedule has changed - there will now be a new major version of Umbraco every 6 months ! with minor versions every 6 weeks?

Our current release policy for uSync means we drift slightly so uSync 9.2 works with Umbraco 9.0 -> 9.3. at this time we don't really have an issue with that.

What we are considering now is how will versioning work going forward ?

v10 - Long Term support

Things to note at this time:

• It is likely at this point that if we want to the uSync v9 codebase will work with both Umbraco 9 and Umbraco 10, this means we won't have to release a separate package to support both versions.
• We want to offer a similar LTS support statement as Umbraco in that the version we release for Umbraco 10 is the one we will commit to supporting for longer

Options

We are currently thinking about two or Three support avenues.

1. uSync Major to match Umbraco Major

We release a v10 to support Umbraco v10, uSync v11 supports v11 ... etc

• We need to consider what would happen to v9 support if we moved to v10
• We would likely stop all but issue fixes for v9 as soon as v10 is released.
• All feature development would be on the v10 branch
• We could if we wanted adopt .net 6 features in the code with no backwards compat issues.

2. Release a hybrid package that supports across multiple versions

A single 'version' of uSync that supports Umbraco 9 and 10 (and 11, 12) until we are forced into a new version by a major change (e.g the new Umbraco UI)

• Would offer better support to people running Umbraco v9.

• We could continue to offer new features to v9 and v10 for longer

• Code maintability would be easier with less branching for 'live' versions.

• Would require multi-targeting the code for .net5 and .net6 (we have some of this in place already)

• Would limit us if we want to use .net 6/7 features

• Supporting new Umbraco features in v10/v11 would need to be backwards compatibly (likely lots of reflection in the code)

3. Major releases on LTS versions of Umbraco

A sort of mix - we would release uSync v10 for umbraco v10, and then try to make that version support the intermedite versions (eg. v11, v12 , v13 of Umbraco.) and release the next version to support v14 through to v17.

• This would mean less 'versions' to worry about
• It might not be possible to support v10 - v13 in one go (e.g new UI would need a new version?)

Summary

At the moment we are probably leaning towards option 1 - mainly because we like the idea of having the version maintain parity and it being easy to see that we support the latest version of Umbraco (good for support and marketing).

but we are still thinking and are seeking input.

[nathanwoulfe]

Keen to see where this ends up - I've had similar issues with versioning, and haven't come to a good solution.

Would be great to see consistency across packages too!

[leekelleher]

I'd also say go with option 1. 👍 I suspect that I've become accustom to that uSync versioning pattern over the years - more so about the majors, I pay less attention to the minor/patch numbers.

re: v9 /v10 - my gut feeling is that v9 would be viewed as a stepping stone to v10 (for LTS) - so yes, when v10 is out, halt on v9 support, as v10 should be easy to upgrade to. _(right?)

For Contentment, I've gone with independent versioning - with a note on the repo's README explaining which Umbraco version it supports. The main reason was that I ended up doing .NET multi-targeting for v8/v9, but also that Contentment was still on v1 when Umbraco v9 was released, so bumping up the major to an 8 or 9 felt far too much.

Thinking further back, with uComponents, I made an Umbraco compatibility grid - a matrix of which package version worked on which Umbraco version. A bit of a mind boggle at the time. 🤷

[KevinJump]

yeah I had a compatibility grid too. http://usync.jumoo.co.uk/docs/8.x/uSync/getting_started/versions

one of the reasons we shifted to v8 made the whole thing much simpler 👍

[ReiterM2000]

I also thought about this a lot for my own packages and decided to go with my own major version with each umbraco major version, thats why I would go with option 1.

From the user perspective I feel that it is easier to know which version I need to install.
From a technical stand point my main reason against targeting multiple Umbraco versions was that I may not be able to use certain .net features aswell as the risk that a higher umbraco version might cause a bug in my package that wouldn't allow supporting the older version anymore.
I also feel that bug tracking and fixing would be much easier and faster if you go with that approach as you don't always have to keep in mind the different Umbraco versions aswell as later check if the package is still working on all of them.