Repository navigation
Build: lerna publish upgrades from 0.x.y to 1.0.0 for breaking changes #1068
Description
We have conventionalCommits configured to be true in lerna.json and use 0.x.y versioning for packages. If a commit log contains BREAKING CHANGE, lerna publish prompts the new versions as follows:
Changes:
- @loopback/authentication: 0.1.1 => 1.0.0
- @loopback/boot: 0.1.1 => 1.0.0
- @loopback/build: 0.1.1 => 1.0.0
- @loopback/cli: 0.1.2 => 0.1.3
- @loopback/context: 0.1.1 => 1.0.0
- @loopback/core: 0.1.1 => 0.2.0
- @loopback/example-getting-started: 0.1.1 => 0.2.0 (private)
- @loopback/example-hello-world: 0.1.1 => 0.1.2 (private)
- @loopback/example-log-extension: 0.1.1 => 0.1.2 (private)
- @loopback/example-rpc-server: 0.1.1 => 1.0.0 (private)
- @loopback/metadata: 0.1.1 => 0.1.2
- @loopback/openapi-spec-builder: 0.1.1 => 0.1.2
- @loopback/openapi-spec: 0.1.1 => 0.1.2
- @loopback/openapi-v2: 0.1.1 => 0.1.2
- @loopback/openapi-v3-types: 0.1.1 => 0.2.0
- @loopback/openapi-v3: 0.1.0 => 0.2.0
- @loopback/repository-json-schema: 0.1.1 => 0.1.2
- @loopback/repository: 0.1.1 => 1.0.0
- @loopback/rest: 0.1.1 => 1.0.0
- @loopback/testlab: 0.1.1 => 0.1.2
We want to upgrade from 0.<x>.<y> to 0.<x+1>.0 instead of 1.0.0.
To work around the issue, we have two options:
- Force all modules to be upgraded to the next minor version (
0.<x>.<y>to0.<x+1>.0) by usinglerna publish --cd-version minor. For example:
Changes:
- @loopback/authentication: 0.1.1 => 0.2.0
- @loopback/boot: 0.1.1 => 0.2.0
- @loopback/build: 0.1.1 => 0.2.0
- @loopback/cli: 0.1.2 => 0.2.0
- @loopback/context: 0.1.1 => 0.2.0
- @loopback/core: 0.1.1 => 0.2.0
- @loopback/example-getting-started: 0.1.1 => 0.2.0 (private)
- @loopback/example-hello-world: 0.1.1 => 0.2.0 (private)
- @loopback/example-log-extension: 0.1.1 => 0.2.0 (private)
- @loopback/example-rpc-server: 0.1.1 => 0.2.0 (private)
- @loopback/metadata: 0.1.1 => 0.2.0
- @loopback/openapi-spec-builder: 0.1.1 => 0.2.0
- @loopback/openapi-spec: 0.1.1 => 0.2.0
- @loopback/openapi-v2: 0.1.1 => 0.2.0
- @loopback/openapi-v3-types: 0.1.1 => 0.2.0
- @loopback/openapi-v3: 0.1.0 => 0.2.0
- @loopback/repository-json-schema: 0.1.1 => 0.2.0
- @loopback/repository: 0.1.1 => 0.2.0
- @loopback/rest: 0.1.1 => 0.2.0
- @loopback/testlab: 0.1.1 => 0.2.0
-
Disable conventionalCommits when breaking changes need to be published and manually select the versions package by package.
-
Do not use
BREAKING CHANGEin commit logs sincefeat(...)will upgrade to the next minor version (0.<x>.<y>to0.<x+1>.0) anyway.
Metadata
Metadata
Assignees
Labels
No labels
Activity
kjdelisle commentedon Mar 1, 2018
I vote for option 3, since semver says that "breaking changes" are a post-1.0.0 concept and that the implication of any 0.x.y API is that things can and will break without notice. (source)
==Added by @bajtos==
Spec item 4 says
kjdelisle commentedon Mar 1, 2018
The only question left to answer, IMO, would be whether or not we can do option #3 based on the existing commit messages in our history, since some of them are marked with "BREAKING CHANGE"
I assume there's some cutoff built in so that it knows which releases already contain those changes, but we should make sure.
raymondfeng commentedon Mar 1, 2018
For those commits that are not published yet, let's use Option 1 to force minor upgrades to reestablish the new baseline.
bajtos commentedon Mar 2, 2018
Ideally, I'd like to see Option 4: fix our tooling to release breaking changes as 0.x semver-minor, features and bugfixes as 0.x.y semver-patch versions. I filled an issue for that: conventional-changelog/conventional-changelog#294
Let's recall why we switched to
0.x.yversions. Quoting from #954:Is this goal still valid?
IIUC, this will require all our dependents to bump up semver-minor part of their
^0.x.yspec whenever we release a new feature. That's not the user experience I would like myself!Another point to consider: the section BREAKING CHANGE is parsed by the changelog generator to tell our consumers what has changed and how to upgrade. See @loopback/context@0.1.2 for an example.
Even if we consider the API as not stable and allow any breaking changes in 0.x releases, I would still prefer if we can start practicing the habit of writing descriptive BREAKING CHANGE entries in our commit messages. Let's build the skill now, while we don't mind too much when we occasionally forget to describe breaking changes, so that we are ready by the time it becomes important.
Having wrote that, I agree that Option 3 looks like the best workaround for short-term.
Possibly related: lerna/lerna#1195
bajtos commentedon Mar 2, 2018
Here is what I have found so far:
conventional-recommended-bumpis returning a stringmajor,minororpatchdepending on what the commit messages say. This is intentional and isn't going to change for 0.x versions as far as the recommendation is concerned. See Do not bump to 1.0.0 when issuing a breaking change < 1.0.0 conventional-changelog/conventional-changelog#239Most tools are using
semver.inc()to compute the next version using the current version number and the recommended bump.semveris not willing to treat 0.x versions differently, see Incorrect Increment for versions < 1.0 npm/node-semver#177.There is a module shifted-semver-increment which provides different behavior for 0.x versions. Unfortunately, they don't shift semver-minor to semver-patch as I proposed in my earlier comment, at least AFAICT - see the code.
Lerna uses
semver.inc()to compute the next version, see src/ConventionalCommitUtilities.js#L86 and feat: adds support for conventional-commits (for CHANGELOG generation and verison bump) lerna/lerna#665. It should be fairly easy to change this behavior, but such proposal may create a lot of controversy and thus take longer to get accepted. We may need to introduce config options to control this behaviour and remove controversy, that will require more effort.virkt25 commentedon Mar 2, 2018
I'm a +1 for writing the Breaking Change message just for changelogs which imo serves as a great reference to see what's been added to a release and often look at those for packages.
That said, changing tooling seems a bit excessive imo since this is only a problem during development but depending on the effort involved it might not be too much work since we do have a while before we release out of preview and as 4.0.0
raymondfeng commentedon Mar 2, 2018
+1 to stay with
0.x.yversioning scheme. At least we can bump minor versions and prevent them from being accidentally picked up by existing apps.+1 to explore a fix in
lernato honor0.x.yupgrade path. We can submit a PR to see what will happen.Upon that, we can continue to use
BREAKING CHANGE.bajtos commentedon Aug 14, 2018
Considering there have been more than 5 months from the last comment, and we are planning to release 4.0 GA in few months (after which lerna versioning won't be a problem anymore), I think this issue can be closed.
bajtos commentedon Mar 9, 2020
Our experimental packages are using
0.xversion, I am re-opening this issue because it's affecting us again.bajtos commentedon Mar 9, 2020
Submitted a PR to lerna to fix the problem: lerna/lerna#2486
bajtos commentedon Jul 24, 2020
lerna/lerna#2486 was merged and published, I am closing this issue as resolved.