How To Handle A Maintenance Branch From Previous Patch Versions That Already Have New Patch Versions?

Mar 11, 2025 by ADMIN 102 views

**Handling Maintenance Branches from Previous Patch Versions**

Introduction

When working with maintenance branches from previous patch versions, it's essential to understand how to handle them correctly to avoid errors and ensure smooth releases. In this article, we'll explore a common use case where you need to create a maintenance branch from a previous patch version, and we'll discuss the correct workaround.

Current Behavior

Let's assume you have the following versions and tags already generated:

2.3.0
2.3.1
2.3.2
2.3.3
2.4.0

You want to create a maintenance branch from 2.3.1 (since there is a particular client with a problem with that version). You do this by running git checkout -b hotfix/2.3.1 v2.3.1. Then, you make the required changes and create a commit with fix(XXX-111): add fix for title. However, when you push the changes, you get the error:

EINVALIDNEXTVERSION The release 2.3.2 on branch hotfix/2.3.1 cannot be published as it is out of range.
Based on the releases published on other branches, only versions within the range >=2.3.1 <2.3.2 can be published from branch hotfix/2.3.1.

This error occurs because version 2.3.2 already exists in your previous released version and tags.

Expected Behavior

When you add the new fix commit, you want it to generate 2.3.1-hotfix.1 in this case. However, the current behavior generates 2.3.2-hotfix.1 instead.

Workaround

To handle this scenario correctly, you can try the following workaround:

Set the config to:

{
  "name": "hotfix/2.3.1",
  "prerelease": "hotfix"
}

This will create the release as 2.3.2-hotfix.1, which is close to what you want.

However, you want the release to be 2.3.1-hotfix.1, not 2.3.2-hotfix.1. To achieve this, you can use the postrelease option instead of prerelease. Update the config to:

{
  "name": "hotfix/2.3.1",
  "postrelease": "hotfix"
}

This will create the release as 2.3.1-hotfix.1, which is the desired outcome.

Conclusion

Handling maintenance branches from previous patch versions requires careful consideration of the release configuration. By understanding the current behavior and expected behavior, you can apply the correct workaround to achieve the desired outcome. In this case, using the postrelease option instead of prerelease allows you to create the release with the correct version and suffix.

Additional Information

The semantic-release version used in this example is 24.2.1.
The CI environment is GitHub.
The plugins used are @semantic-release/commit-analyzer, @semantic-release/release-notes-generator, @semantic-release/github, @semantic-release/changelog, and @semantic-release/npm.
The semantic-release configuration is:

{
  "branches": [
    "next",
    {
      "name": "hotfix/*",
      "prerelease": "hotfix"
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/github",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "assets": ["package.json", "CHANGELOG.md", "package-lock.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

CI Logs

The CI logs show the following steps:

Found git tag v1.147.100 associated with version 1.147.100 on branch hotfix/1.147.0
Published release 1.147.101-hotfix.1 on hotfix/1.147.0 channel

Q: What is the current behavior when creating a maintenance branch from a previous patch version?

A: When creating a maintenance branch from a previous patch version, the current behavior is to generate a release with a version that is out of range. For example, if you create a maintenance branch from 2.3.1 and make changes, the release will be generated as 2.3.2-hotfix.1, even though the desired outcome is 2.3.1-hotfix.1.

Q: What is the expected behavior when creating a maintenance branch from a previous patch version?

A: The expected behavior is to generate a release with the correct version and suffix. In this case, the desired outcome is to create a release as 2.3.1-hotfix.1.

Q: How can I achieve the expected behavior when creating a maintenance branch from a previous patch version?

A: To achieve the expected behavior, you can use the postrelease option instead of prerelease in your semantic-release configuration. Update the config to:

{
  "name": "hotfix/2.3.1",
  "postrelease": "hotfix"
}

This will create the release as 2.3.1-hotfix.1, which is the desired outcome.

Q: What is the difference between `prerelease` and `postrelease` in `semantic-release` configuration?

A: prerelease is used to generate a release with a version that is out of range, while postrelease is used to generate a release with the correct version and suffix.

Q: Can I use both `prerelease` and `postrelease` in my `semantic-release` configuration?

A: No, you cannot use both prerelease and postrelease in your semantic-release configuration. You can only use one of them, depending on your specific use case.

Q: What are the benefits of using `postrelease` instead of `prerelease`?

A: The benefits of using postrelease instead of prerelease include:

Generating releases with the correct version and suffix
Avoiding errors caused by out-of-range versions
Improving the overall release process

Q: How can I troubleshoot issues with my `semantic-release` configuration?

A: To troubleshoot issues with your semantic-release configuration, you can:

Check the CI logs for errors or warnings
Review your semantic-release configuration to ensure it is correct
Consult the semantic-release documentation for more information

Q: Can I use `semantic-release` with other CI tools, such as Jenkins or CircleCI?

A: Yes, you can use semantic-release with other CI tools, such as Jenkins or CircleCI. However, you may need to modify your semantic-release configuration to work with the specific CI tool.

Q: How can I customize my `semantic-release` configuration to meet my specific needs?

A: To customize your semantic-release configuration, you can:

Use the semantic-release API to create custom plugins or integrations
Modify the semantic-release configuration to suit your specific needs
Consult the semantic-release documentation for more information on customization options.