Can I do multiple major version bumps for a given pre-release branch?

[nandorojo]

TLDR

Is there a way to force pre-release versions to do a major version bump on every BREAKING CHANGE, and not just the first breaking change?

---

The docs indicate that if you do a BREAKING CHANGE on a pre-release branch, it will go from 1.0.0 => 2.0.0-alpha.1. That's exactly what I'd expect.

However, it seems like a second BREAKING CHANGE on alpha would increment it to 2.0.0-alpha.2. I understand that this may be desirable for many use-cases.

However, for my use-case, I want any usage of BREAKING CHANGE, even in a pre-release branch, to do a major version bump.

Example

1. Commit breaking change on alpha: 1.0.0 → 2.0.0-alpha.1
2. Another breaking change on alpha: 2.0.0-alpha.1 → 3.0.0-alpha.1

The reason I want this is that I'm tying my major version changes to native code in my React Native app. If (and only if) my major version changes, I need to ship a new binary to the app store.

A pre-release branch is no exception. For every pre-release major version, I ship to TestFlight for testing.

For any non-breaking changes, I just ship an over-the-air update to the corresponding major version.

With the current setup, the major version doesn't increment more than once on a pre-release branch. This would lead to my CI not rebuilding on the app store as it needs to.

[nandorojo]

I believe this could do it, but I'm not entirely sure yet.

{
  "branches": ["master", { "name": "alpha", "prerelease": "alpha" }],
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "angular",
        "releaseRules": [{ "type": "native", "release": "premajor" }]
      }
    ],
    "@semantic-release/release-notes-generator"
  ]
}

Start on 1.0.0. Check out alpha.

Push a BREAKING CHANGE.

Now we're at 2.0.0-alpha.1

And then:

git commit -m 'native: added some native code'

Should this do a premajor and bring me up to 3.0.0-alpha.1?

[nandorojo]

Or, should I be using major instead of premajor? Will it know to do premajor if I use major on prerelease branch such as alpha? (presumably yes)

[nandorojo]

Okay so to answer 2 things:

1. major is sufficient. If you use major on the alpha branch, it will turn it into a premajor which is correct.
2. It does not let me do two major version bumps while on a prerelease branch. I'm hoping there's an answer out there for how to do that.

[nandorojo]

@travi any shot you know if this is possible or not? Thanks again!

[travi]

so, i think the main thing to give the appropriate context to answer this question comes from the relationship between the name of semantic-release and semantic versioning. one of the deepest core purposes of semantic-release is to make semantic versioning simpler to follow correctly. the "semantic" intent is to communicate the impact of the changes in a version since the previous version, so that a consumer understands the level of risk involved in updating. it seems like you are wanting major version increments that arent necessarily communicating breaking api changes to consumers.

to expand, a pre-release is about stability of a release channel on it's way to be promoted to a stable version. because a pre-release is intended to be unstable, multiple breaking changes released to that channel are not intended to increase the target version number beyond a single major bump. this is also true of multiple bug fixes or new features. semantic-release, therefore, bumps the pre-release version number a single increment of the highest impact segment included in that branch. this is by design. the closes supported approach to what you describe would be to merge your prerelease branch into the mainline branch so that the pre-release is promoted to stable. then you can create a new pre-release branch for the increments that are intended to follow that initial major bump.

in addition, it is intended for semantic-release to be responsible for the entire release process. it seems like you are wanting to relate part of the release process that you are intending to be driven by semantic-release with a separate external release process.

semantic-release is a tool to assist in following semantic versioning properly i an automated fashion to prevent mistakes. while it can be twisted to enable other workflows and can be seen as valuable that way because of the pieces that it can automate, those are outside of our supported use cases. semantic-release is not intended to be a general purpose release tool.

[nandorojo]

I understand where you're coming from, and I appreciate your taking the time to give a detailed answer. I thought it over for the past day. To address some of your points:

it seems like you are wanting major version increments that aren't necessarily communicating breaking api changes to consumers.

To clarify, this isn't true. I want major version changes to indicate breaking api changes to consumers, where the consumer is me deploying my app via a CI.

Some context: are two kinds of deployments of a React Native app: 1) over-the-air, and 2) new App Store build.

In an ideal world, I would only ship updates over-the-air, since it's much simpler.

However, only certain changes to code can deployed be over-the-air (if you only edit JavaScript, no native code).

If you edit native code and send an over-the-air update, every user's app will break. Thus, adding native code is a breaking change, which should be a major update.

Every time there is a major update, the CI should build on the App Store, rather than send an update over-the-air.

the closes supported approach to what you describe would be to merge your prerelease branch into the mainline branch so that the pre-release is promoted to stable. then you can create a new pre-release branch for the increments that are intended to follow that initial major bump.

That's correct. It's not an ideal approach for me, since I'd like to be able to add multiple releases onto a prerelease branch while coding. And it's likely we'll have multiple breaking changes along the way, each of which will require a new App Store build.

This is a very common use case for app developers. You ship many versions onto TestFlight before merging to production. Each version sent to TestFlight is breaking.

It's possible my best bet is to just try to reduce breaking changes, and any time I have one, I need to merge to master before adding another. I'd prefer a way around it (I could even make a custom plugin), but I understand you think this is an anti-pattern.

it seems like you are wanting to relate part of the release process that you are intending to be driven by semantic-release with a separate external release process.

I suppose this is true. I want semantic versioning in my app. The only difference is I ship to my React Native app rather than NPM.

semantic-release is not intended to be a general purpose release tool.

I get that you have to keep your scope confined. I was hoping to get to use semantic-release, since it seems so well thought-through and handles a lot of edge cases that would be hard to build from scratch.

At the end of the day, the only thing I'm missing from this lib is being able to increment the major version for multiple breaking changes while on prerelease. I get that this isn't officially supported, and goes against your plans.

If I were to try to solve this on my own, would it be possible if I made a plug-in? For instance, could I make a custom way to analyzeCommits to achieve this if I went off on my own and worked with the Expo team?

FWIW, I'm also open to using 0.x.y versioning, where every minor version is breaking. But it also doesn't seem to jive with your description of how semantic versioning works in a pre-release stage.

[yonitou]

Hey @nandorojo
I'm 100% in your case. Did you find a solution to manage it ?

[nandorojo]

I spent forever trying to automate this and now I just manually edit the version number to fire releases.

[arthurmarcal-gm]

Hello @nandorojo,

I'm currently grappling with a challenge similar (I think) to what you've described and I was hoping you could shed some light on your approach to manually editing versions. I've been searching for a viable solution that I can integrate into my CI/CD pipeline for what feels like an eternity. Additionally, @travi, do you have any advice on whether it would be beneficial to incorporate semantic-release into my workflow, and if so, how? (Although I think I already understood that this is not the ideal/desirable default behavior.)

To provide some context, our backend needs to support multiple API versions to ensure compatibility with older versions of our native mobile apps still in use by customers who haven't updated to the latest versions on the App Stores. It's crucial for us to maintain these multiple versions across three separate branches to mirror the production environment for development and testing purposes.

I'm currently working on automating versioning for an AWS Serverless API (comprising API Gateway and Lambda) using the serverless-framework. The strategy I've devised involves using Lambda Aliases, API Gateway Stages, and semantic-release to manage the major version numbers, which are then used as arguments for the Lambda aliases.

Our setup on AWS includes three isolated stages/accounts, each corresponding to a GitHub branch:

• "dev" (development): The primary environment for integrating new changes and features, with frequent commits from our backend engineers.
• "homolog" (staging): This is (I guess) our release candidate environment, which is suppose to be more stable and where QA testing occurs.
• "prod" (production/main branch): The live production environment.

I've been attempting to use semantic-release by designating "dev" and "homolog" as pre-release branches.

Within our workflow, we create numerous feature branches that merge into "dev". The continuous integration and deployment process then automatically extracts the major version number for the alias/API Version (e.g., 1.0.0-dev.1 -> 1.0.0-dev.2 -> 1.0.0-dev.3 - not a problem so far).

At the end of our sprint, we merge the branch "dev" into "homolog" by opening a pull request (e.g., if homolog is at 1.0.0-homolog.1, it moves to 1.0.0-homolog.2 - not a problem as well, since there's no major change - the deploy will happen in v1).

Following QA and any necessary bug fixes, we merge "homolog" into "prod", resulting in a version increment (e.g., 1.0.0 to 1.1.0).

The challenge arises when there has been a breaking change in a pre-release branch, which as an example might have already been merged into "homolog" and then into "prod" (e.g., 2.0.0-dev.1 to 2.0.0-homolog.1 and eventually to 2.0.0 in "prod"). Suppose we start a new sprint and a new feature (in a new branch - eg: feature/new_breaking_change) with another breaking change is needed. Eventually we will merge this new branch into "dev" and I expect a new tag like "3.0.0-dev.1", but instead, I receive "2.0.0-dev.2". This happens despite semantic-release indicating that a major version bump should occur. Here's what semantic-release prompts:

`[12:24:57 AM] [semantic-release] › ℹ Found git tag v2.0.0-dev.1 associated with version 2.0.0-dev.1 on branch dev
[12:24:57 AM] [semantic-release] › ℹ Found 2 commits since last release
[12:24:57 AM] [semantic-release] › ℹ Start step "analyzeCommits" of plugin "@semantic-release/commit-analyzer"
[12:24:57 AM] [semantic-release] [@semantic-release/commit-analyzer] › ℹ Analyzing commit: Merge pull request #12 from my_company/feature/bc_2

BREAKING CHANGE: second breaking change
[12:24:57 AM] [semantic-release] [@semantic-release/commit-analyzer] › ℹ The release type for the commit is major
[12:24:57 AM] [semantic-release] [@semantic-release/commit-analyzer] › ℹ Analysis of 2 commits complete: major release
[12:24:57 AM] [semantic-release] › ✔ Completed step "analyzeCommits" of plugin "@semantic-release/commit-analyzer"
[12:24:57 AM] [semantic-release] › ℹ The next release version is 2.0.0-dev.2`

Any guidance on resolving this issue would be greatly appreciated.

[travi]

• "dev" (development): The primary environment for integrating new changes and features, with frequent commits from our backend engineers.
• "homolog" (staging): This is (I guess) our release candidate environment, which is suppose to be more stable and where QA testing occurs.
• "prod" (production/main branch): The live production environment.

I've been attempting to use semantic-release by designating "dev" and "homolog" as pre-release branches.

what you describe is a gitflow workflow. semantic-release does not support gitflow. while you might be able to misuse the pre-release workflow to simulate a gitflow-like workflow, it is not the intended use of the pre-release workflow and not officially supported. you would find semantic-release to be a better fit when following continuous integration with a github-flow or trunk-based development workflow. if you strongly prefer gitflow, you will likely find that semantic-release is not a good fit