The Subtle Art of the Changelog

• towncrier

  5 732 7.3 Python

  Manage the release notes for your project.

  

We used to... somewhat attempt manual changelogs. Every time it came to a release the release manager would ask around for what the key changes were, and we usually ended up with only a couple of entries.

Now, we use https://github.com/twisted/towncrier . Every change goes through pull requests, and every PR must have a newsfragment file - and we enforce this with a test that fails if it isn't present (with convenience functions of rewriting the number to match the PR if you name the news file XXX.{category}). If it's not a user-facing change, then we just have a category that is ignored.

On releases (or on individual PRS along the way), the release manager generates the changelog, but also edits them into a relatively coherent style (or rewrites developers news fragments along the way).

Every change has a note written aimed at the user. Every entry in the changelog has a link to the relevant PR or commit. We have much better changelogs now.

• bmlt-root-server

  2 12 6.8 PHP

  This is the Main Root Server Repo for the Basic Meeting List Toolbox

  

I have a CHANGELOG.md for all my projects.

Fairly boring, but useful.

Here's a changelog that covers about 14 years: https://github.com/bmlt-enabled/bmlt-root-server/blob/main/C...

• InfluxDB

  www.influxdata.com sponsored

  Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.

  

• keep-a-changelog

  10 5,914 7.9 Haml

  If you build software, keep a changelog.

• changesets

  30 7,998 5.7 TypeScript

  🦋 A way to manage your versioning and changelogs with a focus on monorepos

  

https://github.com/changesets/changesets works well for generating changelogs.

• ohmyzsh

  559 168,701 9.5 Shell

  🙃 A delightful community-driven (with 2,300+ contributors) framework for managing your zsh configuration. Includes 300+ optional plugins (rails, git, macOS, hub, docker, homebrew, node, php, python, etc), 140+ themes to spice up your morning, and an auto-update tool so that makes it easy to keep up with the latest updates from the community.

  

• WorkOS

  workos.com sponsored

  The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  

Suggest a related project