How to announce an open-source release that people read
By Bright Oparaji9 min read
Write release notes for the person upgrading, not for the person who wrote the code: breaking changes and upgrade steps first, then what is new for them, then the rest. Announce every release in the project's own channels, and only the ones that change what someone can do with the project anywhere else.
A release is the one piece of news an open-source project produces without extra effort. What usually goes wrong is the last step: the notes are a list of commit subjects, or a version number and nothing else, and the release never leaves the repository. This post covers the notes, the changelog behind them, which releases deserve an announcement outside the project, and how to write one.
Release notes people read
The reader of release notes has one question: what does this mean for me? They are deciding whether to upgrade, whether it will break something, and whether the thing they asked for has arrived. A list of commits answers none of those directly.
Order the notes by how much the reader needs to know before upgrading:
- Breaking changes and upgrade steps. If anything stops working, say what, and say exactly what to change. Put this at the top even when the rest of the release is more exciting. A user who upgrades and finds their build broken has a worse day than one who missed a new feature.
- What is new for the user. Describe each change as something the reader can now do, not as something the code now does. "You can now validate a file without loading it into memory" is better than "Refactored the reader to stream".
- Fixes. Say what used to go wrong, in terms a user would have noticed, and link the issue if there was one.
- Everything else. Internal changes, dependency bumps and refactors can go in a short list at the end, or stay in the changelog.
Credit people. Name the contributors whose work is in the release, and the people who reported the bugs that got fixed. It costs one line and it is often the only thanks they get.
If you follow Semantic Versioning, the version number already carries part of this message: a major version means incompatible API changes, a minor version means backward compatible features, a patch means backward compatible fixes. Say in the notes whether you follow it, so readers know how much to trust the number.
GitHub Releases and a changelog
On GitHub, a release is built on a Git tag and carries notes and, if you need them, binary files. GitHub's documentation points out that people can choose to be notified of new releases without following everything else in the repository, which makes the release page a real channel for the people most likely to care. When publishing a release you can also mark it as a pre-release, and if Discussions is enabled, create a discussion for it, which gives users somewhere to ask questions that is not the issue tracker.
GitHub can also generate release notes automatically from merged pull requests, with a list of contributors and a link to the full comparison. A .github/release.yml file lets you group pull requests into categories by label and leave some out, such as dependency updates from a bot. Generated notes are a good first draft. They are not finished notes, because pull request titles are written for reviewers. Read the list, add the breaking changes and upgrade steps at the top, and rewrite the two or three items a user will care about most.
A changelog file is the long memory behind the releases. Keep a Changelog sets out a format that many projects use: the latest version first, a date on each version, an entry for every version, and changes grouped as Added, Changed, Deprecated, Removed, Fixed and Security. It also recommends an Unreleased section at the top, so changes are written down when they are merged rather than reconstructed on release day. Its view of pasting the commit log is blunt: commit diffs are full of noise, because a commit records a step in the code's history and a changelog entry records the difference that matters.
The Unreleased section is the habit that makes the rest easy. If each meaningful change gets a line when it lands, the release notes are mostly written before you tag.
Which releases are worth announcing beyond the repository
Every release belongs on the release page and in the changelog. Far fewer belong in front of people who have never heard of the project. The test is whether the release changes what someone can do with the project, or who it is useful for.
Worth announcing outside the project:
- A major version, especially one that removes a long-standing limitation or changes how the project is used.
- A feature that opens the project to new users, such as support for a new platform, language or framework.
- The fix for a problem many people hit, where the problem itself was a reason people stayed away.
- A first stable release after a long period of pre-releases.
Not worth announcing outside the project:
- Patch releases with routine fixes.
- Dependency updates and internal refactors.
- Releases whose only news is the version number.
The second list still matters to existing users, and your own channels serve them well. Posting it in a general community is what teaches that community to scroll past your name. The guide to promoting an open-source project calls releases the recurring surface, and that works only if what surfaces is worth reading each time.
Where to announce
Start with the channels the project already has. They reach the people most likely to upgrade, and they need no one's permission.
- The GitHub release itself, with notes written as above.
- GitHub Discussions, if you use it, with a short announcement linking the release.
- The project's own mailing list, blog, Discord server or social accounts, if it has them.
- The README, if the release changes the install line, the first example or the list of supported platforms. A README that describes the previous version is a common gap after a big release, and the post on improving a GitHub README covers what the first screen has to say.
Then, for the releases that pass the test above, go to the communities where your users already are. The list of communities for open source covers what each one welcomes. A few are a natural fit for release news: ecosystem newsletters that collect notable releases, the showcase channel of a framework's Discord or Slack server when the project is built for that framework, and Mastodon, where a release with a story or a screenshot travels further than a bare link. Read each place's rules before you post. The post on posting without getting removed explains why fit and permission are separate questions.
Hacker News is a special case. The Show HN guidelines say that new features and upgrades, with "Foo 1.3.1 is out" as the example, are generally not substantive enough to be a Show HN, and that a major overhaul is probably fine. A routine release does not qualify. A release that changes what the project is might. The Show HN launch guide covers how to post when it does.
Write the announcement so it stands without the link
Most people who see an announcement will not click it. The ones who do click because the post told them enough to know the release is relevant. So the announcement itself has to carry the news.
A useful announcement answers four questions in a few sentences:
- What the project is, in one line, for readers who have not met it.
- What changed, as something the reader can now do.
- Who it matters to, so the right readers stop and the others move on.
- What it costs to upgrade, if anything.
Here is an invented example, for a fictional CSV validation library:
Version 2.0 of our CSV validation library is out. It checks files of any size by streaming them, so an export larger than your machine's memory can now be validated. If you validate exports from a data warehouse, this is the release you were waiting for. One breaking change: the
strictoption is now the default, and the upgrade notes show the one-line change to keep the old behaviour.
And an invented example of the same release written badly:
v2.0 released! Lots of improvements and fixes. Check out the release notes!
The second one tells the reader nothing they can act on, and it asks for a click before it has earned one. In a real announcement, any number you give should be one you measured.
Fit the length to the place: a Mastodon post wants the first two sentences and an image, a newsletter submission one sentence and the link. Write it fresh for each place rather than pasting the same text everywhere.
Doing this on a schedule
The part that slips is not writing a good announcement. It is noticing that a release deserves one, a week after it shipped, when the notes say only the version number. Orviqa finds new GitHub releases each day without a webhook, and reads the subject of every commit since the previous tag rather than relying on the release notes. It drafts an announcement when asked, or automatically for releases worth announcing if you turn that on for a repository, with up to two drafts, one per channel. Nothing is posted without your approval.
Release announcement checklist
- Breaking changes and upgrade steps are at the top of the notes.
- Each new feature is described as something the user can now do.
- Fixes say what used to go wrong, in a user's terms.
- Contributors and bug reporters are credited.
- The changelog has an entry for this version, dated, with changes grouped by type.
- The README still matches the current install line and first example.
- The release is posted in the project's own channels.
- It passes the test for announcing elsewhere: it changes what someone can do with the project.
- Each outside announcement follows that place's rules and is written for that place.
- The announcement says what the project is, what changed, who it matters to and what upgrading costs, without needing the link.