[Case Study] Managing releases with version --deferred

[eps1lon]

Disclaimer: I might read more into yarn version than it should be used for.
Possibly duplicate of #326

What package is covered by this investigations?

Whatever package is responsible for yarn version

Describe the goal of the investigation

Releasing canaries from master with only using the yarn CLI

Investigation

As far as I understood the documentation the following workflow should be used

git checkout master # version: 0.0.1
git checkout feature-a
yarn version prepatch --deferred
git checkout master
git merge feature-a
# in CD
yarn version apply --all # version: 0.0.2-0
yarn workspaces foreach npm publish --tolerate-republish # in case we iterate over unchanged workspaces
# end CD
git checkout feature-b # version: 0.0.1, nextVersion: 0.0.2-0
yarn version prepatch --deferred
git checkout master
git merge feature-b
# in CD
yarn version apply --all # version: 0.0.2-0 (already published)
yarn workspaces foreach npm publish --tolerate-republish
# end CD

This would only result in a single version being published since yarn version prepatch --deferred only updated the nonce which is not part of the version string.

Currently CD would have to commit changes applied to the repository so that subsequent PRs would create a new version. This is not viable since it a) defeats the purpose of deferred b) doubles to commits on master (noise) and c) requires every PR to be up-to-date with master which doesn't scale to big repositories.

The simplest solution would probably include the nonce in the version string for release candidates. Though I'd need to check if semver ranges apply which could cause issues though you shouldn't use ranges for canaries anyway IMO.

Another problem is that yarn version downgrades:

# version 0.0.1
yarn version preminor --deferred # nextVersion: 0.1.0-0
yarn version prepatch --deferred # nextVersion: 0.0.2-0

I would also abuse yarn version patch to upgrade release candidates to stable releases:
0.0.1-0 -> 0.0.1
0.1.0-0 -> 0.1.0
1.0.0-0 -> 1.0.0
Not sure if this is expected or if there (should) exists a command.

[arcanis]

Currently CD would have to commit changes applied to the repository so that subsequent PRs would create a new version. This is not viable since [...]

This is actually what I had in mind. For example, taking the Yarn repository as example, everytime I create a new release a workflow runs that will run apply --all and upgrade everything into a single commit.

a) defeats the purpose of deferred b) doubles to commits on master (noise) and c) requires every PR to be up-to-date with master which doesn't scale to big repositories.

The idea is that you don't want to release for every commit, especially if you're working on a big project - if you were, then I'd agree that it would be problematic to double the number of commits.

Instead, the idea is that every time you want to "commit" your packages and release them all to the registries, that's when you run apply --all. Does that make sense?

Another problem is that yarn version downgrades:

That shouldn't be the case - is it also the case on master? I merged a few fixes related to that yesterday evening.

[eps1lon]

Does that make sense?

Sure but that's just not what I want. We get frequent requests about when which bugfix will be released and I don't want to bother with this anymore. Being able to just refer to canary releases (especially automated ones) is one less release-related issue I have to worry about. The other solution is to just release it as stable but this gets really spammy to the point of multiple releases a day.

If you don't want to support automated releases then that's fine. It's a package manager after all and not a release manager.

In the end it's probably not that hard to take the version in nextVersion, insert the commit sha and apply that version instead.

But that reminds me of another issue: Say I do commit applied versions then I now have to apply different pre* strategies. If I have a patch rc in version say 0.0.2-0 and apply yarn version prepatch I get 0.0.3-0 when 0.0.2 was never released as stable. I could prevent that by running prerelease instead but that's another condition I have to check first. I would expect 2x yarn version prepeatch to result in 0.0.2-1 instead of 0.0.3-0.

That shouldn't be the case - is it also the case on master? I merged a few fixes related to that yesterday evening.

I can check.

[arcanis]

Though I'd need to check if semver ranges apply which could cause issues though you shouldn't use ranges for canaries anyway IMO.

There will be a sort problem with the nonce because a later release may have a lower nonce. Similarly, hashes don't play well because they are compared lexically. The best would probably be the depth in the master branch.

If you don't want to support automated releases then that's fine. It's a package manager after all and not a release manager.

Yep - the version command actually was an optional plugin until not too long ago precisely because there are many ways of managing releases that really depend on the tradeoffs you want to do. Maybe it should move back to being a plugin 🤔

I would expect 2x yarn version prepeatch to result in 0.0.2-1 instead of 0.0.3-0.

The inc strategy is handled by semver, this is how they chose to interpret the pre family:

premajor in one call will bump the version up to the next major version and down to a prerelease of that major version. preminor, and prepatch work the same way.

[eps1lon]

There will be a sort problem with the nonce because a later release may have a lower nonce.

Just checked the spec again and you're correct. pre-release is considered when comparing precedence.

Still not sure having the canary version in version control is viable. The amount of merge conflicts likely dwarfs the usefulness of having CD handled by yarn.

That shouldn't be the case - is it also the case on master? I merged a few fixes related to that yesterday evening.

I can check.

Works on master with
Usage Error: The target version (2.0.1-0) is smaller than the one currently registered (2.1.0-0); use -f,--force to overwrite.. https://github.com/eps1lon/berry/blob/842cd3406305779a9330b3e29ade95eef75ebab6/packages/acceptance-tests/pkg-tests-specs/sources/commands/version.test.js#L16 should be the test for it.

Nit:

index d45fc560..3c347955 100644
--- a/packages/acceptance-tests/pkg-tests-specs/sources/commands/version.test.js
+++ b/packages/acceptance-tests/pkg-tests-specs/sources/commands/version.test.js
@@ -4,7 +4,7 @@ const {
 } = require('pkg-tests-core');
 
 describe(`Commands`, () => {
-  describe(`version check`, () => {
+  describe(`version`, () => {
     test(
       `it shouldn't work if the strategy isn't semver and there is no prior version`,
       makeTemporaryEnv({}, async ({path, run, source}) => {

I think yarn version is in a pretty good state (deferred being the real hero here). I guess canaries, nightlys etc. should be handled by a different command anyway. Probably something like yarn apply and then adding -canary.x where x is determined by querying published packages. I guess I'll experiment a bit what frequency works best. No point of having CD if it frequently breaks CI builds.

[arcanis]

Closing this issue for now, feel free to open a new one when you have other feedback! Also note I've implemented yarn version check -i last week which makes it a breeze to decide the state of all the packages that will need to be bumped 😃