release-it

A handy pair of scripts for managing your change log and initiating a versioned release.

What problems does it solve?

The aims of these two scripts are to:

• Make the release process as painless as possible and remove all the mandrolic elements.
• Stop un-released entries in the change log from causing merge conflicts in feature pull requests.
• Help maintain a consistent look to the change log.

Single command release

Our process for releasing Stroom is largely driven off an annotated git tag. We update the change log to reflect the version number we are about to release. We then tag git with an annotated tag that contains the release version as its title and the changes in the release as the content. Github actions will then kick in and perform a build for this release version and if successful will publish artefacts to Sonatype, Dockerhub and GitHub releases.

The above used to involve multiple manual edits to the change log and various git commands to initiate the release. Now you just run ./tag_release.sh, respond to a couple of prompts and you are done.

Preventing merge conflicts

Our bug fixes and new features are generally all done on feature branches. Each one will update the top of the change log file to record what has changed in the application. These change log entries almost always result in merge conflicts (on the change log file) in the pull requests which slows down the process of merging in fixes/changes.

To avoid these conflicts, un-released change log entries are now stored in separate uniquely named files. With each change entry in its own file there will be no conflicts caused by the change entries. If you use the convention of including the issue number in your feature branch, you can now just do something like this:

./log_change.sh auto "Add vim key bindings to editor"

Getting started

To get the latest version run this from the root of your git repository:

for f in log_change.sh tag_release.sh; do; curl -Lso $f https://github.com/at055612/release-it/releases/latest/download/$f && chmod u+x $f && echo "Downloaded $f $(grep -o "Version: .*" $f)"; done

Dependencies

• bash v4 or greater.
• GNU grep is required.
• GNU sed is required.
• log_change.sh uses fzf for item selection if installed. It works without fzf but it is not as nice a UX.
• log_change.sh uses jq for processing GitHub API responses. Inferring change categories from issue types is not supported without jq.

Installing both fzf and jq is recommended.

The scripts

log_change.sh

This script creates unique change entry files for unreleased changes.

Features:

• Creates change entries linked to GitHub issues.
  • Validates the issue number.
  • Writes the issue title to the change entry file.
  • Supports issues in different repositories.
  • Can derive the issue number from branch name (e.g. branch gh-nnn- or nnn-), else prompts for it.
  • Multiple change files per issue.
  • Tries to derive the change category from the GitHub issue type (if set), else prompts for it.
• Creates simple change entries not linked to GitHub issues.
• ISO 8601 dated filenames for implicit ordering and uniqueness.
• Adds a block of random text to the file to make it unique for git's change detection algorithm.

Examples:

# Interactive mode. It will try to read the GitHub issue number from
# your current branch (e.g. branch: gh-1234-fix-dead-locks).
# It will also try to infer the change category from the GH issue type.
# It will open your default editor to edit the change text in the created file.
./log_change.sh

# Log a change with no associated issue.
# Prompts for change category and opens editor.
./log_change.sh 0

# Explicit type and text, will derive issue from branch.
./log_change.sh Bug auto "Fix database dead locks during purge job"

# Log a change with no associated issue
./log_change.sh Bug 0 "Fix typo on about screen"

# Log a change for issue #1234
./log_change.sh Bug 1234 "Fix database dead locks during purge job"

# Log a change for issue #1234
# Your default editor will open the created skeleton change file
./log_change.sh 1234

# Log a change for an issue in a different repository
./log_change.sh Bug gchq/stroom#2424 "Fix database dead locks during purge job"

# Log a change for an issue in a different repository
# Your default editor will open the created skeleton change file
./log_change.sh Bug gchq/stroom#2424

# List all unreleased changes
./log_change.sh list

# Select a change file to edit from all available unreleased changes
./log_change.sh edit

# Edit the change file for the issue in your current branch (e.g. branch: gh-1234-fix-dead-locks)
./log_change.sh edit auto

# Show the help
./log_change.sh help

tag_release.sh

This script initiates a versioned release by updating the CHANGELOG and creating an annotated git tag.

Features:

• Creates its own configuration file on first use (if not found).
• Creates an empty change log file on first use (if not found).
• Adds the content of the unreleased change entry files (created by log_change.sh) to the CHANGELOG.
• Guesses the next version based on the previous release.
• Adds a new version heading to change log.
• Adds/updates the version compare links in the CHANGELOG.
• Commits and pushes the change log changes.
• Creates an annotated git tag using the release version number and change entries.

Credits

Credit for the idea of storing unreleased change log entries in separate files goes to:

https://about.gitlab.com/blog/2018/07/03/solving-gitlabs-changelog-conflict-crisis/

This repo is my take on their idea.