Hotfix on a release

[HampB]

Hey, trying to set up release please for a monorepo. One issue i cant seem to find any good info about is how to deal with hotfixes.

For example:

• Push feature to main
• Release-please pr is merged and release created.
• additional features are added to main
• bug is reported on initial release

Now an hotfix needs to be done on the initial release, how do I best go about this?

Without release-please i would branch out from release tag, do fix, release patch and then merge into main. But this seems to trigger another release when the merge to main happens.

Thanks in advance for any help!

[DennisSmolek]

Curious because I have a similar flow but we dont patch backwards like you suggest.

Say you are at:

• 2.0 with your "initial" release
• Feature release 2.1
• Feature release 2.2

Now you want to put a hotfix that relates to code in 2.0
Releases 2.1 and 2.2 are live, and unless you intend on removing them they will stay live

So your hotfix makes things: 2.2.1

Is that not what you want?

[HampB]

Not exactly @DennisSmolek , but maybe it's just our strategy being a bit unconventional.

In your example, I agree that it would work. However, our approach is to push an initial release (let's say 2.0) and continue adding features to main without immediately creating new feature releases. Now, suppose we discover a bug that needs fixing in 2.0:

• Release 2.0.0
• Feature 1
• Feature 2
• Hotfix 2.0.1 (fixing a bug in 2.0)
• Feature 3
• Release 2.1.0 (including Feature 1, 2, and 3)

Under this approach, we’d have to release all new features alongside the hotfix, but we'd prefer to wait until our scheduled release day for new features. That’s the main challenge we're trying to address.

[jdlovins]

@HampB I've been thinking of this as well as I am trying to cover all the bases to implement this at my job. I think really what I am going to do is just have images built on like /feature/* and /fix/* branches and would deploy a fix image to prod if there is currently work staged on main. Not the most ideal thing if you have workflows setup to run on releases that you would have to mimic/bypass but I don't see a way around it. Definitely a downside of staging work in main prior to releasing. Maybe feature flags could be useful.

[collindutter]

@HampB this is the approach we take, maybe it will be helpful.

[nicomouss]

@HampB Been testing release-please in order to integrate it on various projects, and it works fine regarding the workflow you are using.

Having this branch setup:

• a main (trunk) branch
• release/* branches (you create a release/* branch whenever you want to hotfix a given release)

Using release-please action, what you want to do is have something like below in your configuration, having release-please triggered when you push on main (trunk) branch, and also when you push on release/* branches.

on:
  push:
    branches:
      - main
      - release/*

permissions:
  contents: write
  pull-requests: write

name: release-please

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          # this assumes that you have created a personal access token
          # (PAT) and configured it as a GitHub action secret named
          # `RELEASE_PLEASE_TOKEN` (this secret name is not important).
          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
          target-branch: ${{ github.ref_name }}
          release-type: node

Taking your example, this is what you will have, step-by-step:

1. Release 2.0.0 => When you merge the release-please PR, github release v2.0.0 is created and tag v2.0.0 is created.
2. Feature 1 => You commit "feat: Feature 1" on main (git commit -m "feat: Feature 1"). When you push main (git push origin main), a new release-please PR is created for v2.1.0. Changelog contains "feat: Feature 1".
3. Feature 2 => You commit "feat: Feature 2" on main (git commit -m "feat: Feature 2"). When you push main (git push origin main), the release-please PR for v2.1.0 is updated. Changelog now contains "feat: Feature 1" and "feat: Feature 2".
4. Hotfix (fixing a bug in 2.0.0) => To do that, you create a new branch "release/v2.0.1", branching out from tag v2.0.0 (git checkout -b release/v2.0.1 v2.0.0). You commit "fix: my hotfix" on release/v2.0.1 (git commit -m "fix: my hotfix"). When you push that branch (git push origin release/v2.0.1), a new release-please PR is created for v2.0.1 (the PR is created on branch release/v2.0.1 so it is independent from the previous PR created on main for v2.1.0). Changelog contains "fix: my hotfix".
5. Back on main (git checkout main), you cherry-pick the commit(s) (git cherry-pick commit-sha) you have applied on branch release/v2.0.1 (or you can merge release/v2.0.1 branch (git merge release/v2.0.1), instead of cherry-picking. Personally I prefer the cherry-picking method, as it keeps a linear commit history on main). This makes sure the hotfix is also available for future releases. When you push main (git push origin main), the release-please PR for v2.1.0 is updated. Changelog now contains "feat: Feature 1", "feat: Feature 2", and "fix: my hotfix".
6. Now you can merge the release-please PR for v2.0.1: github release v2.0.1 is created and tag v2.0.1 is created. That means at this point you have deployed your hotfix. You can delete release/v2.0.1 branch.
7. Feature 3 => You commit "feat: Feature 3" on main (git commit -m "feat: Feature 3"). When you push main (git push origin main), the release-please PR for v2.1.0 is updated. Changelog now contains "feat: Feature 1", "feat: Feature 2", "fix: my hotfix", and "feat: Feature 3".
8. Release 2.1.0 (including Feature 1, 2, 3, and the hotfix) => You merge the release-please PR, github release v2.1.0 is created and tag v2.1.0 is created.

Hope this helps.

[nicomouss]

Following up with my last comment, the only thing to be taken care of is when there is a version clash between the two PRs.
This situation is explained here.

In our example, this means you'd have the following scenario:

• Release 2.0.0
• fix 1 on main => release-please PR created on main is targeting v2.0.1
• fix 2 on main => release-please PR on main still targeting v2.0.1
• Hotfix 2.0.1 (fixing a bug in 2.0) => release-please PR created on hotfix branch is targeting v2.0.1
• fix 3 on main => release-please PR on main still targeting v2.0.1

In that case, deploying v2.0.1 for the hotfix is correct (that is, you merge the release-please PR on branch release/v2.0.1, and github release v2.0.1 is created, as well as tag v2.0.1).

Now at this point, on main you also have the release-please PR targeting v2.0.1. That's the problem.
To fix that, just bump the version number on main using an empty commit containing a release-as directive:
git commit -m "chore(release): bumping version number" -m "release-as: 2.0.2" --allow-empty.

In your global workflow, the rule to follow is: every time you are about to merge a release-please PR, just check if the target version of the PR has not been already used for a previous release. If it has been already used, bump the version number yourself using the release-as directive to fix the version clash.

[airtonix]

@nicomouss have you thought about automating that in a closed or tag event workflow:

• on event
  • use version in event
  • to check if open release prs are targeting said version
  • no? exit 0
  • yes
    • reach out and add commit to relevant release prs release-as: computed bump

[HampB]

Thanks @nicomouss for the thorough explanation!
Seems like you have an solution for most of my issues, guess i'll have to give it a try when i get some time over :-)

[nicomouss]

@airtonix Yes it is definitely automatable as needed. As it is kind of an edge case, so far I haven't dived into the subject of automatically bumping the version number in case of a conflict.

At first sight, I feel it would be simpler to trigger the automatic version check/bump as a step configured to run just after the release-please step in the wokflow. So that this version-clashing resolution is only triggered when release-please action has finished running.

We'd have the following yaml template:

on:
  push:
    branches:
      - main
      - release/*

permissions:
  contents: write
  pull-requests: write

name: release-please

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
          target-branch: ${{ github.ref_name }}
          release-type: node
      - name: "Version clash resolution"
         uses: custom_action_to_manage_version_clashes

Happy if someone wants to keep exploring the idea !
Ultimately that is something that could be integrated within the realease-please action itself, so that it's fully transparent.

@HampB Glad this help. Thank you for initiating this discussion, we were in the same boat basically, and this helped a lot into exploring the solution I came up with.

If you don't want to mess up with already-existing repo(s), I suggest you test the proposed solution on a new repo, using empty commits to simulate real-case scenarii (git commit -m "feat: Feature 1" --allow-empty). Once you get the feel of the general workflow, you can integrate release-please in your project(s).

[airtonix]

Happy if someone wants to keep exploring the idea !

yep this is a topic near and dear to my heart.

[airtonix]

@nicomouss Thinking about this more.

I'm playing around with the idea putting version conflict handling in the PR workflow:

• is this a release-please pr? sniff labels
  • no: exit 0
• are the computed version bumps going to end up conflicting with existing ones?
  • no: exit 0
• otherwise
  • exit 1

Then the workflow can be made to block the PR until this is resolved with more commits or a /release-as command in a comment.

This only works if you've setup release-please with a PAT instead of the secrets.GITHUB_TOKEN since we're running workflows triggered by events created from other workflows.