I am developing my first package and am using the opinionated package as the foundation. When I setup my project it was using the inital Umbraco 17 release but I am wondering if I should still use the intial release as my test site or keep the test site updated to the latest LTS? What are the thoughts of package devs on this? As far as I can tell there is nothing in my package that would break between 17.0 and 17.4
Hi @Eaglef90 ,
I can share my take on this as I recently published a uMediaOps package. For the package target I would pick the lowest for e.g. for 17 it would be 17.0.0. It’s because if I set the package target to let’s say 17.4 then it might break when trying to install on sites having lower versions.
For the test site, I would pick the latest minor (e.g., 17.4). Because, minor versions are not supposed to contain breaking changes, they usually includes bug fixes, UI adjustments, etc. Testing on 17.4 ensures you are building against the most stable, bug-free state of the CMS. If let’s say a user on 17.2 experiences a visual glitch that doesn’t exist in 17.4, you don’t rewrite your package to fix Umbraco’s old mistake. You just advise the user to patch their site to the latest minor release.
Hope it helps!
1 Like
I have a few packages released / in progress and my general standpoint on this is that you should develop against the latest version that you’re developing at the time, but set the base version to 17.0.0. If you know there’s a breaking change, then set that as the minimum when you release. My reason for this is that you don’t want to “accidentally” update someone’s core version because they install your package.
Unless you cap it, your release will be auto available for future Umbraco versions.
1 Like
<ItemGroup>
<PackageReference Include="Umbraco.Cms.Web.Website" Version="[17.0.0,20.999)" />
<PackageReference Include="Umbraco.Cms.Web.Common" Version="[17.0.0,20.999)" />
<PackageReference Include="Umbraco.Cms.Api.Common" Version="[17.0.0,20.999)" />
<PackageReference Include="Umbraco.Cms.Api.Management" Version="[17.0.0,20.999)" />
<PackageReference Include="Umbraco.JsonSchema.Extensions" Version="0.3.0" PrivateAssets="all" />
</ItemGroup>
for me.. as 21 is the next LTS on a new NetCore version.. ps <20.999 as <21.0.0 would include 21 RC’s
https://psw.codeshare.co.uk/#umbraco-versions
1 Like
For CSP Manager, I take a different approach, there was a security patch for 17 a little while ago so the next release support that as its minimum. As its a security focused package I feel it should help enforce good habits.
I decided to support packages with the same lifecycle as Umbraco. So my major versions match the major version of Umbraco that it supports. So my versions are scoped to only that major versions like this: [17.0.0,18.0.0).
Maybe the package would work for the next major without any changes, but I don’t know that beforehand. That’s why I don’t want to have more broad versions support for a package. When the new Umbraco major comes out, it’s also a moment to do breaking changes and cleanup and see if everything is still done according to the latest standards.
I also think there is absolutely no reason why someone wouldn’t update Umbraco to the latest minor version that they are on. So when I start a package, I take the latest version of Umbraco and I support it only from that version and up. I think that sticking to the x.0.0 version for a package sound good on paper because you support all versions of that Umbraco major, but in reality it can give you the annoying transient vulnerable nuget errors.
So when I update the minimum supported Umbraco version of my package, I hardly consider that a breaking change because I feel like you should keep your Umbraco instance up to date anyway. I see it the same as @MattW . I don’t neccessarily update the minimum Umbraco version I support every time I make a new release, but when it’s needed, I will do it. Especially when there is a security patch.
2 Likes
Thanks all for the input, but I am not talking about the minimum package target version. My question is specifically about what version to test against. So if anyone has input on that please let me know.
When I start my package, as I said, I take the latest version of Umbraco for my package, but also the latest version of Umbraco for the Umbraco testproject that accompanies the package project.
Personally I think it’s implicit.. that if you set a min/max.. then you should test across the latest minor for each currently available major. (with AI and playwright MCP this could be automated?)
There is also context.. if you’ve been developing this package since v17.0.0 then along the way you will have updated the test site along the way, so can say it works 17+.. (and then you can only test in the latest minor, assuming you don’t add your own breaking changes) Also if you have the time to add unitTests etc..
If you are only starting now and only test on the latest, then I think being honest about your strategy has equal merit..
“This package has been actively tested against v 17.X.X, but observing breaking changes we think it should work in 17.0.0+, also to allow for rapid use in future versions we don’t set a maximum but be advised issues may arise” ??
It’s a catch 22.. I guarantee it works for these versions.. and you’ll have to wait for the next release… at one end.. to the it’s open-ended but untested so have at it , (and lots of grey in between)
It’s probably one of those you can’t please all the people all the time, but if you upset the wrong person they might never want to use the package again. 
PS: Also just to mention some companies have an active policy of no early adoption, say 6 months grace before a release is considered stable (I’ve heard tell of some government requirements being 6yrs for infrastructure software before it’s an accepted provider 
)
So don’t think you can just assume every client should/can update to the latest minors…
We’ve had several recent minors that were fixing regressions, to illustrate the early adopter downside.
1 Like
Technically, when you create the package and test on v17.0.0, if everything is right, it should work on ALL minor version of 17.x because minor versions should not have breaking changes 
But in reality…that’s not always the case. I’m really not going to test against every minor version of Umbraco, but I will update my Umbraco test project every time I work on it.
1 Like
Must be misunderstanding you…
[17.0.0,18.0.0).
so you started at 17.0.0. and created your package…
you then add to the package (a version or two of core might have been released)..
so now its 17.4.0… and you package is still [17.0.0,18.0.0). but you only test on 17.4.0 at this point?
but 17.4.0 does have a breaking change #22307 Application URL: Add ApplicationUrlDetection setting to control application URL auto-detection
so <17.4 might now not work??
(17.3 has a breaking change also #22028 Dependencies: Update MailKit to 4.15.1)
There is the when is a breaking change a breaking change… :-0
I was meaning at that point you check 17.0.2, 17.1.0, 17.2.2, 17.3.5.. to strictly maintain your [17.0.0,18.0.0). ?
Then there is testing and testing.. with psw it’s simple enough to spin up those 4 options and see if it still builds and unittests are successful at least?
But it’s all a moving target, depending on how much time you are spending in your packages, I’d hope all packges are treated as minimally tested (as they are mainly community built and who has the time).. and internal testing happens on consumption.
But as long as it’s clear on the package methodology (what testing has been done, and your intention for previous and forward compatabilty), then that at least informs the end user..
ps watch out for 18.0.0-rc1 is semantically < 18.0.0
Well, I have serious issues with breaking changes in Umbraco minor versions. Minor versions simply should not have breaking changes. So if there are, there is really no way to counter this. So let’s take my case.
So te constraint is [17.0.0,18.0.0) and let’s say my package version is 1.0.0. Now 17.4.0 has a breaking change assume that my package is affected. I will then update my package to version 1.1, change the reference to [17.4.0,18.0.0) and fix the issue. So yes, version 1.0.0 will technically say that it will work on any minor Umbraco 17 version, but in reality it won’t.
But this all stems from the issue that there is a breaking change in a minor version of Umbraco which it absolutely shouldn’t have. So there is no planning against breaking changes in minors to be honest.
My point is that I’m not going to test my package against every single version of Umbraco that comes out. If there is a hotfix that fixes a security issue, it might read that and proactively set my minimal Umbraco version to that when I do the next development to more or less force consumers to update their Umbraco.
Btw. I don’t consider Umbraco updating dependencies to a newer minor version a breaking change. Once again if you take the conversion seriously that minor versions don’t have breaking changes this is never an issue and resolved correctly by the NuGet parser.
But then again you fix the issue with 17.4.0.. such that it’s still compatible with 17.0.0 and no need to update the version boundaries..
And then you keep your userbase happy too as they might want a new feature in your next release but not want to update core..
Ps that would be your v1.1
If you didn’t then you’d need to go to v2.0 as your package has a breaking change? 
It’s quite the evocative topic…
I think for me it’s context.. which [17.0.0,18.0.0) doesn’t reveal the whole story or intent… 
To throw another little wrench into the discussion, Lotte’s " Opinionated Umbraco Package Starter Template" includes a centralized package management file.
Directory.Packages.props:
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<!-- Allow floating versions so extensions can align with the host Umbraco project's package versions -->
<CentralPackageFloatingVersionsEnabled>true</CentralPackageFloatingVersionsEnabled>
</PropertyGroup>
<ItemGroup>
<!-- Umbraco API packages - Used by extension templates -->
<PackageVersion Include="Umbraco.Cms.Api.Common" Version="17.4.2" />
<PackageVersion Include="Umbraco.Cms.Api.Management" Version="17.4.2" />
<PackageVersion Include="Umbraco.Cms.Web.Common" Version="17.4.2" />
<PackageVersion Include="Umbraco.Cms.Web.Website" Version="17.4.2" />
</ItemGroup>
</Project>
Notice the line:
<CentralPackageFloatingVersionsEnabled>true</CentralPackageFloatingVersionsEnabled>
So, I was unfamiliar with this, so I asked AI, and this is what was returned:
CentralPackageFloatingVersionsEnabled (MSBuild / Central Package Management)
What it does: Controls whether individual projects in a solution can override the package version constraints defined in Directory.Packages.props.
| Value | Behavior |
|---|---|
false (or omitted) |
All projects are locked to the centrally-defined version constraint. Use this if you want to enforce a range. |
true |
Individual projects can override the central constraint — in either direction, up or down. |
When to use it: Only useful when different projects in the same solution legitimately need to resolve the same package at different versions. A common scenario is an extension package that must align with whatever Umbraco version its host project uses.
Important gotcha: Floating versions are not restricted to floating up. With true, a project can resolve to a version both above and below your specified range — so if you’re using a version range (e.g., [17.0.0,18.0.0)) with the intent of enforcing it, set this to false or omit it entirely. Enabling floating effectively makes your range advisory rather than enforced.
From my understanding of this, I will be setting it to false, but something to note since many package devs might be using that template.
Great find on the CentralPackageFloatingVersionsEnabled
Some more thoughts..
I think this actually comes from the umbraco package extension template which Lotties uses during setup.
dotnet new umbraco-extension -n "PackageStarter" --site-domain "https://localhost:44300" --include-example
opinionated-package-starter/template/setup.cmd at main · LottePitcher/opinionated-package-starter
That same extension template can also be used for adding multiple projects into a solution, with the idea that you move the Directory.Packages,props into the solution root.. (which you have mentioned), or if you add a core class library projects into lotties after templating..
The package extension template takes a param
dotnet new umbraco-extension --version 17.1.0 -n MyExtension -ex
Umbraco-CMS/templates/UmbracoExtension/Directory.Packages.props at main · umbraco/Umbraco-CMS
Which if you don’t specify, defaults to *
Now with Lotte’s " Opinionated Umbraco Package Starter Template as there isn’t a parameter to match the Version that you can pass into the umbraco package extension template, it will always be *…
But that’s not really an issue as the package is meant to be for nuget package generation (and not just project generation) and you should see when you pack the package, the process concretes the version that * resolved at pack time. (you may or may not want this)
Also of note.. if you are just creating a project to sit in your solution you need to be mindful of * during CI/CD as if will do as you ask and fetch the latest version of umbraco for the project and as you main www project depends on it, you might get an umbraco update you didn’t mean… (topic on the forum somewhere just can’t find it presently)
1 Like