Skip to main content

Changelog and versioning

Overview​

Maintaining a changelog for your codebase is crucial as it provides a clear and structured record of all notable changes made over time. This helps developers, stakeholders, and users to easily track the progress and evolution of the project, understand the context of changes, and identify when specific features or fixes were introduced. Additionally, a well-maintained changelog enhances transparency, facilitates better communication within the team, and aids in troubleshooting by providing a historical reference of modifications.

Our changelog maintenance strategy ensures that all notable changes are documented in a structured and consistent manner. This strategy involves creating individual changelog entry files for each pull request, merging these entries into a single entry, and following a calendar versioning scheme.

Outline​

1. Creating changelog entry files​

For each pull request, a separate changelog entry file is created. This file should contain a brief description of the changes introduced by the pull request. The file is typically named using the pull request number or a unique identifier to avoid conflicts.

2. Merging entries​

We use Changie to merge individual changelog entries into a single entry for the given release. Changie automates the process of collecting all changelog entry files and combining them into a comprehensive changelog for the release. This ensures that all changes are documented in a single, cohesive entry.

3. Calendar versioning​

Our project follows a calendar versioning scheme. This means that our version numbers are based on the date of the release. The format we use is YYYY.MM.BUILD, where which makes it easy to identify when a particular version was released.

Workflow​

  1. Create a Changelog Entry: When a pull request is created, add a new changelog entry file in the .changes directory. This can be done by running pnpm changie new, which will start an interactive prompt to create the changelog entry.
  2. Automated PR creation: The CICD pipeline will automatically create or update a release PR once a new changelog entry is added to the .changes directory.
  3. Releasing: Simply merge the created release PR, which will take care of updating CHANGELOG.md to reflect the new release.

By following this strategy, we ensure that our changelog is always up-to-date and provides a clear history of changes for each release.

Tailoring to your own needs.​

This strategy is tailored to our specific needs and may need to be adapted to suit your project's requirements.

In .changie.yaml you can configure the changelog generation to suit your needs. For example, you can add or remove change types here, as well as default page elements. See the documentation for further options

If you prefer tag-based versioning follow the following steps:

  • remove CHANGELOG.md, .changie.yaml and .changes
  • in .github/workflows/prepare-release.yaml remove the create-version-command element
  • run pnpm changie init.

This will recreate all configurations, defaulting to tag-based versioning.