[feature] Automate release process

[Dhanus3133]

Our current release process is entirely manual. It often involves a lot of time spent digging through git logs, manually writing and formatting the changelog, and remembering a sequence of git commands to tag and release a new version. This process can be time-consuming and creates friction that can discourage us from making frequent releases.

The Proposal

To make this easier and faster, We can use a helper script to automate the most repetitive parts of making a release. The goal wouldn't be to remove humans from the loop. A manual review is still essential, but to handle the tedious, error-prone tasks for us.

Proposed Core Functionality

@nemesifier and I put some thought into what a first version of this script could do. The main focus would be on perfecting the changelog generation. As discussed, it should be able to:

• Automatically scan git history since the last release tag.
• Understand our commit conventions, like [feature] etc.
• Handle breaking changes by looking for a ! (i.e., [change!]).
• Group commits into logical sections: Features, Changes (Backward incompatible changes, Other changes), Dependencies and Bugfixes.
• Be smart about dependencies, showing only the latest version of a package if it was updated multiple times.
• Allow to skip commits from the changelog by using a flag like [skip changelog] on commit description.

[pandafy]

I am adding the workflow which I used for writing changelogs for the last release 24.X. I hope this will provide the necessary context.

1. List all commit messages since the last release with the one-line formatting
2. Remove commits which are tagged ci/qa/chores/tests
3. Sort the commits based on their categories
4. Remove fix commits which was added due to interim bug added by a feature or a change
5. Use the commits flagged as deps to track the dependency changes. Lately. I have found that directly checking the diff for ci.yml and requirements.txt is quicker to note down all dependency changes.
6. Now the tedious work, reviewing each commit message and rephrasing it so it makes sense. In order to provide necessary context, I add relevant hyperlinks to the each point in the changelog. The URL could be of issue, PR or docs section.

[Dhanus3133]

Here’s the approach I’m thinking for the CI changes:

1. Once the changelog is ready with the script, we’ll first create a new branch for the specific release version (e.g., release/1.2.0), before raising a PR.
2. Then, we’ll raise a PR containing only the changelog changes and version bump, targeting that release branch.
3. After the PR is merged into the version branch, we’ll create a new tag for the release, which will include the changelog updates/version bump too.
4. Finally, we’ll merge the changelog changes into the master branch as well to keep it in sync.

[nemesifier]

Here’s the approach I’m thinking for the CI changes:

1. Once the changelog is ready with the script, we’ll first create a new branch for the specific release version (e.g., release/1.2.0), before raising a PR.

You mean once a change log has been generated by the script and verified manually?

A branch like that likely exists on most modules and it's just "1.2". Some modules may not have it and in that case we can create it when we release.
Please look at the existing modules.

2. Then, we’ll raise a PR containing only the changelog changes and version bump, targeting that release branch.
3. After the PR is merged into the version branch, we’ll create a new tag for the release, which will include the changelog updates/version bump too.
4. Finally, we’ll merge the changelog changes into the master branch as well to keep it in sync.

This is valid only for bugfix releases, eg: from 1.1.1 to 1.1.2.

Feature releases (eg: from 1.1.x to 1.2.0) happen on master.

There's also something else you should aware of, please see:

Github Action: https://github.com/openwisp/openwisp-utils/blob/master/.github/workflows/reusable-version-branch.yml
Docs: https://openwisp.io/docs/dev/utils/developer/reusable-workflows.html

One question for @pandafy: does the github action reusable-version-branch create the branch if it doesn't exist or do we need to create it?

[pandafy]

One question for @pandafy: does the github action reusable-version-branch create the branch if it doesn't exist or do we need to create it?

If my memory is serving right, it automatically creates a new branch in the repository.

openwisp-utils/.github/workflows/reusable-version-branch.yml

Line 61 in cf945ba

git push origin $VERSION

[pandafy]

@nemesifier @Dhanus3133 have you explored https://git-cliff.org/?

From the documentation, I think it will be able to generate most part of the changelog.

[Dhanus3133]

have you explored https://git-cliff.org/

I have started looking into it.

There are a few things I’m trying to figure out with Git Cliff:

1. Once bug-fix releases are done, those commits shouldn’t show up again in the changelog when doing a feature release on the master branch.
   (There's a --skip-commit flag, but we might need to add some logic to filter out those commits properly.)

2. We should avoid duplicate dependency entries. For example, with Dependabot, only the latest version bump should show up and not every intermediate update.

3. The existing changelog shouldn't get overwritten, we should make sure it always appends new entries.

[nemesifier]

have you explored https://git-cliff.org/

I have started looking into it.

There are a few things I’m trying to figure out with Git Cliff:

1. Once bug-fix releases are done, those commits shouldn’t show up again in the changelog when doing a feature release on the master branch.
   (There's a --skip-commit flag, but we might need to add some logic to filter out those commits properly.)
2. We should avoid duplicate dependency entries. For example, with Dependabot, only the latest version bump should show up and not every intermediate update.
3. The existing changelog shouldn't get overwritten, we should make sure it always appends new entries.

It all sounds like we should use git-cliff to produce output that we then postprocess to obtain the result we want.
It seems it still removes the need for implementing a lot of new logic, which is good.
I believe we'll need some post processing logic in any case, but please let's make sure we write that logic in python and we have unit tests for it.
I'd make a wrapper command for this, the wrapper can call git-cliff and then give the output to our post-processing tool.

[nemesifier]

Let's keep in mind there's 2 flows:

• bugfix release (assume if not on master or main branch)
• standard release flow (assume if on master or main branch)

The main difference is that the bugfix release needs an extra step to port the change log of the bug fix release to the master branch with a commit like [docs] Added change log for X.X.X.

There's a few important points missing from the plan here, we want this release helper tool to relieve the maintainer from boring tedious repetitive work, so we want also the following:

• Perform the version bump for us
• Have a manual revision step which does the following:
  • Optional AI revision, ask the user confirmation before proceeding, if user confirms, ask ChatGPT to revise the change log, ask the maintainer if he wants this: yes/no, default yes, after the response of chatgpt we should be able to:
    1. accept
    2. decline
    3. ask for further revision by supplying a different prompt
  • Manual revision step:
    1. accept without further changes
    2. make changes with vim (opens vim editor interactively)
    3. wait for user to make changes with their preferred text editor / IDE (just wait until the user has made changes and presses a specific key to resume)
• Commit version bump and change log changes to a different branch, open pull request, wait for approval and merge, check every 20 seconds whether the PR was merged, once merged switch to the target branch and pull
• Create signed tag (eg: git tag -s ...) and push it
• Draft release on github via API request, use the change log just generated but convert it to from restructured text to github markdown, return URL in the command line output to allow for manual review and approval, allow approving via command line, once approved the release is published (if already published manually on github just skip)
• If it was a bugfix release, port the bugfix release change log to the main/master branch