All old bootstrapper scripts are now broken

[kjbartel]

What You Are Seeing?

Breaking changes introduced in cake 1.0.0 affect all old build.ps1 scripts because the packages.config fetched targets 1.0.0. All of the older build.ps1 scripts do not work with new cake 1.0.0. This has broken a lot of automated builds and we now need to go to old branches to get them building again.

What is Expected?

build.ps1 script should continue to work without any modification. If you introduce a breaking change then the path to packages.config which is fetched for 1.0.0 should be a different path. Old scripts should then get the old (still compatible) version (0.38.5) of the nuget package.

What version of Cake are you using?

Well everyone who doesn't have a packages.config file will automatically use 1.0.0.

Are you running on a 32 or 64 bit system?

64-bit

What environment are you running on? Windows? Linux? Mac?

Windows

Are you running on a CI Server? If so, which one?

TeamCity

How Did You Get This To Happen? (Steps to Reproduce)

Use any old script which uses single dashes for the arguments and don't have a packages.config file under tools, and then run the script.

[augustoproiete]

Hey @kjbartel, the way to avoid this issue for good is to follow our recommendation of pinning the cake version that you use, which in your case it means storing the packages.config file in your source control system, effectively locking the version of Cake you get every time, so that the bootstrapper never has to fetch a new one until you decide it's time.

We have great documentation on how to do this for each different Cake runner, and even a video if you check the Reproducible Builds section on the website.

Before we do every release (even minor ones) we send a friendly reminder about this on all channels we engage with the community, including Twitter, Gitter, Slack, and more.

It's unfortunate that you didn't have your version locked this time, but now you know the path forward and can avoid the same issue when future versions of Cake are released.

NB: The same concept applies to all addins, modules, and recipes you use on your build scripts. We recommend you always specify the version of the extension you're loading, to avoid surprises, by appending the &version=x.y.z segment in the directive.

[augustoproiete]

Hey @kjbartel ideally no one should need to see our reminders about new releases as they'd have already pinned their Cake version from the start! 😄

But anyway, feel free to suggest ideas on how to improve this experience, keeping in mind not to degrade the upgrade experience we have today.

One other thing that is worth mentioning is that the .NET tooling got a lot better in recent years, and we now recommend everyone to use the dotnet cake tool installed as a local tool in the repository, which by default guides you on the right path of creating a tool manifest file with a specific version of the Cake runner declared, and store it in source control as part of the initial setup.

[kjbartel]

I would think that since there are release bands that you should have packages.config files for each release band. That is, 0.X releases shouldn't have breaking changes compared to previous 0.X releases, while 1.X will / can introduce breaking changes from 0.X, and 2.X will introduce breaking changes from 1.X etc. (as outlined in your docs https://cakebuild.net/docs/getting-started/lifecycle). You don't want to remove the ability to automatically get the latest (non-breaking) version within the same release band. So it would have been nice if the 0.X packages.config was at one path (i.e. https://cakebuild.net/download/bootstrapper/packages) and 1.X at another (e.g. https://cakebuild.net/download/bootstrapper/packages/1.X). New scripts would then specify the new location. And you could even have another path for latest if you really wanted.
Now, yes sure it could also be done by the user by specifying a range of versions for cake in the packages.config file rather than pinning a single version. I would just say that there will be people like myself and others in my company that didn't know that they had to pin the version of cake and it's simply been working for years until now when it will have just broken. And yes you recommend to use the dotnet cake tool but for existing legacy projects setup years ago which aren't even built using the dotnet commandline tool this isn't a straightforward change.

[pascalberger]

I think you need to decide if you want to have deterministic and reproducible builds or not. If this is something important for you, and our suggestion is to follow this path, then there's is no other way than to pin to an exact version and never automatically update Cake or any dependencies. Even if we say we won't break the API in 1.x releases, and they contain only bug fixes and backwards compatible features, this doesn't mean that it won't have the potential to break your build. If this would be the goal of 1.x it would essentially mean that we won't be able to do anything on it, as even a bugfix has the potential to break a build if a build script relies on the behavior of the bug.
If deterministic builds are not important for you than you can ignore this, but need to live with the risk of having your build breaking every now and then.

[pascalberger]

Another thing to add here: If you're using extensions things got even more complex, as they are released by the broader community. Even if we setup guidelines (e.g. to use SemVer, breaking API should result in a bumped major version), we won't have control over it and you can't rely on every one in the ecosystem following the guidelines (as you can't for example with NuGet packages). For example if an extension author bumps the requirements for supported Cake version to the next major version of Cake, but doesn't bump major version, then your builds will break again.

[pascalberger]

And final note: Even if we would implement something like you suggested with separate package.config files for major versions to allow automatic rolling forward in a major version, and extension authors follow SemVer, I can't work.
Imagine you're using Cake 1.0 together with an addin version 3.0, which is compatible with Cake 1.0. Both of them are not pinned. This works fine as long as we're on 1.x. But as soon as Cake 2.0 is released, and the addin releases version 4.0 to be compatible with it, it will break. With the fixed package.config we would stay on latest 1.x, but how should Cake now know that it needs to use addin versoin 3.x and not 4.0, without having any hint? Of course we would be able to implement some try/error approach by trying with 4.0 first, when finding out that it isn't compatible, trying out previous version, etc. But this would introduce a lot of magic which probably isn't expected by most users, leads to other issues, especially performance wise.