Changelog Driven Releases — Save time and mental overhead

Maybe you are writing a library used in another project. Or maybe you are publishing an open-source product. In most cases, you need some way to mark stable releases for your project.

If your project or team doesn't have a reliable process to mark & trigger releases yet, we provide a super-efficient tool for this use case. It's our Changelog Driven Release action, and it's part of our DX toolkit now.

This article should take less than 5 minutes to read and 5 minutes to install in your project.

You need Versioning, Changelogs, and Automations

You should pin usable versions of your project as releases. If you use an explicit numbering system, it's even better. After all, semver has become the standard by now.

You should have a Changelog in your project. It acts as a single source of truth for what changed between any two releases. It makes notable changes to the project explicit. We recommend the Keep A Changelog format.

Finally, if your team doesn’t have release automations yet, your process’ documentation is probably missing or outdated. You’re taking the risk of running into errors, or you might have a very low bus-factor.

Let me show you an open source action that adds a very clear & explicit way to release software and encourages your team to maintain the Changelog:

Changelog Driven Release

Add the Changelog Driven Release action to your repository.

This is just one small configuration change - add the following workflow to your GitHub Actions:

on:
	push:
		branches: [main]
		paths: [CHANGELOG.md]
	pull_request:
		branches: [main]
		paths: [CHANGELOG.md]

permissions:
	contents: write

jobs:
	release:
 		uses: ipdxco/changelog-driven-release/.github/workflows/pr.yml@v1

(Find the latest instructions in the README)

Releases can be triggered with a single change to your Changelog

When someone on the team makes a notable change, ask them to update the Changelog. The description of their change should go in the Unreleased section.

## [Unreleased]

### Added

- A new release system

It’s up to you how strict you want to be with enforcing guidelines like this one.

For example, Kubo enforces maintainers to add a Changelog line in most PRs. But you can explicitly bypass this rule with a `skip-changelog` label (example). What the Kubo team wanted to achieve was to strike a balance between a reminder and a rule.

We definitely recommend going for something un-intrusive first. Keep it contributor-friendly and refine the process along the way. It’s worth remembering that you can always go back and add all the missing Changelog entries retroactively.

When you want to release a new version, just rename the unreleased section with a new version number. That’s a good time to add missing entries too. The important thing is to make the system work for you and your team.

## [Unreleased]

## [0.0.1] - 2023-12-11

### Added

- A new release system

Declaring the new version in the Changelog triggers your release.

As long as there is a version, whether you use `semver` or something else, our system will adapt to what you need.

The action will do most of the work now

On a release Pull Request, our workflow comments with details about the release you’re about to create. You can go ahead and modify it however you wish!

When a team member merges the PR, the action publishes the release. The resulting Github release can look something like this.

That's it!

This release system reduces the mental overhead of managing versions. It encourages communication between maintainers and users through PRs and Changelogs.

It saved hours of maintenance for our teams

• The Changelog is now a mandatory waypoint for the team. This encourages maintainers and users to engage with it
• It's extensible: it's possible to trigger subsequent releases of other artifacts, such as Docker containers, NPM packages, etc.
• The release process is explicit, visible, and self-documenting for the entire team. You can even use Codeowners to define who can release the project.

That's it. Was it 5 minutes? We hope this guide saves you hours 🤞