Support Maintenance Releases

[jbcpollak]

Maybe this is just a documentation issue, but what would the process for making a maintenance release be?

Say for example branch main always has the latest releases, and the current release is v0.2.0, but you need to make a patch release to an older version like v0.1.0, so you need to branch from the v0.1.0 and make a tweak, then release it: will release know to only follow that branch and make the release v0.1.1, or will it make v0.2.1?

Also, and I'm not sure there's a good way to prevent this but what happens if you make a feat() change on the maintenance branch? really that should be un-releaseable or never get merged - maybe that's out of scope for release.

[kettanaito]

Hey, @jbcpollak.

There are two ways you can perform such a release.

Local

You can branch from v0.1.0, make the changes, commit and push them, and then run release publish. During the run, the tool will analyze the latest present tag, which on your feature branch should be v0.1.0 (release commit will be created by the tool). It'd do so by fetching all the tags:

release/src/utils/git/getTags.ts

Line 7 in dcfa47c

const allTags = await execAsync('git tag --merged')

I frankly don't know if this command respects the feature branch of lists all the tags from the remote. You may want to test this.

And then sorting them, so the latest one is always the first one:

release/src/utils/git/getLatestRelease.ts

Line 11 in dcfa47c

const allTags = tags.sort(byReleaseVersion)

Finding v0.1.0 as the latest tag, the library will then proceed, analyzing your commits and generating a new release tag v0.1.1.

Remote

On remote, you follow the same procedure apart from the last publishing step, as it's usually integrated in your CI.

The only issue is that once Release sees a new fix: foo commit on the top of the HEAD, it will think it's a new fix relatively to the latest published version. In this regard, it will attempt to do v0.2.1, which is not expected.

My initial idea was to suggest you trigger the release job manually and select a specific branch to do the release from (can do that from the GitHub Actions UI) but that won't stop your automated CI on main from trying to publishing that fix as v0.2.1.

Not sure how to approach this. Do you have any ideas? How would the tool know that you're fixing something relatively to an old release? I don't think that's the regular Git flow. Such maintenance releases should be a special case. Maybe their changes are not pushed to the HEAD?

You can still do:

1. Branch from v0.1.0.
2. Do the changes, commit and push.
3. Run the release job at that feature branch (not main).
4. Once the release is done, delete the feature branch.

While this would work in terms of releases, you'd lose your fix in Git and that's not acceptable.

Are you suggesting we need something like "skip this commit" flag? 🤔

[jbcpollak]

I'm not entirely sure what the solution is here, but this conversation did remind me how we solved this in past lives and it relates to #19. Also I want to point out I'm approaching this from the point of view of a terminal product, not a library. So for us "breaking change" is a bit undefined (maybe the config files or integrations require work), and also we deploy to enterprise customers who often don't want any changes other than their hotfixes, so I'm coming from that perspective.

Lets assume your main/default branch always gets major.minor.patch versions.

I don't think there's any way for a tool to be able to look at existing releases and correctly make an automated decision. For the following examples lets assume when we want to make a maintenance release, its always a branch off main from the point of the 0.1.1 tag.

• Scenario 1, current releases off main: 0.1.0, 0.1.1. No need to make a branch, commit to main and you'll get 0.1.2
• Scenario 2, current releases off main: 0.1.0, 0.1.1, 0.1.2. In this case, because of semver arguably you theoretically you just commit to main and release 0.1.3. Though in some enterprise environments that's not going to fly.
• Scenario 3, current releases off main: 0.1.0, 0.1.1, 0.2.0. Branch at 0.1.1, you'd want the release tool to generate 0.1.2 of the branch. To do that I think release would need to only look at versions created from the branch in question, which I think is difficult. Also...
• Scenario 4, current releases off main: 0.1.0, 0.1.1, 0.1.2, 0.2.0. Branch at 0.1.1, you'd want the release tool to generate 0.1.1-hotfix.1 (or something similar).

I'm not sure its possible for release to properly handle scenarios 3 and 4 with 0 config.

Here is a suggestion: we can solve this and #19 at the same time: add support for defining prefix and metadata to ossjs.release.config.js.

A hotfix branch would use metadata:

module.exports = {
    script: "npm release",
    metadata: "hotfix"
};

This would generate 0.1.1+hotfix.1 in our example above - another commit and release to the same branch would generate 0.1.1+hotfix.2. basically the major.minor.patch calculation is shut off

Using the metadata field, only the number after the string increments by one per release. To deploy these releases, you'd have to be explicit about which exact hotfix you want, because there are no precedence rules. I think this is fine.

One problem with this is what if some wanted actual build metadata in their versions? I can think of a couple of different solutions for that but I think the best one might be to just (eventually) allow a ${BUILD_METADATA} environment variable that is always appended to the metadata in the config (if it exists), or just is the metadata if the config param isn't set. I wouldn't want to set hotfix in an env var because changing the CICD pipeline specifically for a hotfix is a pain, but this could (eventually) support both use cases.

Note: I actually think hotfixes are a missing limitation from semrel, but I don't see that changing any time soon.

I'll comment on #19 about how beta's could work.

[kettanaito]

Hi, @jbcpollak. There's been some progress around this and Release now supports multiple profiles.

I believe you can now define a designated profile that will trigger a custom release:

// release.config.json
{
  "profiles": [
    { "name": "latest", "use": "<YOUR_REGULAR_RELEASE>" },
    { "name": "dev", "use": "npm publish --tag beta" }
  ]
}

Then, configure your GitHub Actions to trigger the right release publish -p dev command only when on the correct Git branch:

# .github/workflows/release.yml
on:
  push:
    branches: [dev]
jobs:
  release:
    steps:
      - # Checkout the repo
      - name: Release
        # Provide the "name" of the profile to publish.
        run: npx release publish -p dev