Open Source Library Release Checklist

An open source release checklist for npm, PyPI and other registries: semantic version, changelog, package contents check, secure publishing and announcement.

Typical schedule per library release
The checklist 4 sections, 18 items
Variables {{package}} {{version}}
Start from CI

Use this template Free, no credit card. Imports the checklist into your Runbook organization.

Use this checklist when you publish a new version of a library or tool to a public registry such as npm, PyPI, crates.io, RubyGems or Maven Central. Once a version is public, other projects depend on it within minutes. You cannot quietly fix a bad release: most registries never let you reuse a version number, even after you unpublish it. The checklist keeps each release predictable for users and safe for the maintainers.

Who owns it

The maintainer who cuts the release owns the run. In projects with several maintainers, the person who publishes should not be the only one with registry access, and access should be protected with two-factor authentication. Contributors whose changes are in the release can be credited in the notes.

Common pitfalls

The wrong files in the package. Missing build output, or test fixtures and local secrets included by accident. Inspect the packed archive before you publish, for example with npm pack --dry-run.
A breaking change in a minor version. Users trust semantic versioning to upgrade safely. If you change or remove public behaviour, it is a major version, even if the change looks small.
Publishing from a laptop. A local publish is hard to reproduce and depends on one person's token. Publish from CI, ideally with trusted publishing or provenance where your registry supports it.
A changelog that lists commits. Users need to know what changed for them and what they must do. Group the notes into breaking changes, features and fixes.

The checklist: Publish {{package}} {{version}}

Prepare

Changes since the last release are reviewed and the version bump follows semantic versioning
Breaking change: major. New backwards-compatible feature: minor. Bug fix only: patch.
{{version}} is set in the package manifest and any version constants
Changelog for {{version}} is written with breaking changes, features and fixes
Migration notes are written for breaking changes optional
Deprecation warnings added in earlier versions are honoured or extended optional

Verify

CI is green on the release commit across all supported runtime versions
Dependencies are checked for known vulnerabilities and unwanted new licences
Packed archive contents are inspected for missing build output and unwanted files
Package installs and works in a clean example project
Documentation and README examples match {{version}}

Publish

Release commit is tagged with {{version}} and the tag is pushed
{{package}} {{version}} is published from CI with trusted publishing or provenance where supported
Registry page shows {{version}} with the correct files, metadata and dist-tag
Pre-releases should not be published under the latest tag.
Release is created on GitHub, GitLab or Codeberg with the changelog for {{version}}

Announce and follow up

Release is announced where users follow the project, such as discussions, chat or social media optional
Issues that are fixed in {{version}} are closed with a link to the release
New issues are watched for the first days after the release
Docs site is rebuilt and versioned docs for {{version}} are published optional

Checklist as Markdown

# Publish {{package}} {{version}}

## Prepare
- [ ] Changes since the last release are reviewed and the version bump follows semantic versioning
  Breaking change: major. New backwards-compatible feature: minor. Bug fix only: patch.
- [ ] {{version}} is set in the package manifest and any version constants
- [ ] Changelog for {{version}} is written with breaking changes, features and fixes
- [ ] Migration notes are written for breaking changes (optional)
- [ ] Deprecation warnings added in earlier versions are honoured or extended (optional)

## Verify
- [ ] CI is green on the release commit across all supported runtime versions
- [ ] Dependencies are checked for known vulnerabilities and unwanted new licences
- [ ] Packed archive contents are inspected for missing build output and unwanted files
- [ ] Package installs and works in a clean example project
- [ ] Documentation and README examples match {{version}}

## Publish
- [ ] Release commit is tagged with {{version}} and the tag is pushed
- [ ] {{package}} {{version}} is published from CI with trusted publishing or provenance where supported
- [ ] Registry page shows {{version}} with the correct files, metadata and dist-tag
  Pre-releases should not be published under the latest tag.
- [ ] Release is created on GitHub, GitLab or Codeberg with the changelog for {{version}}

## Announce and follow up
- [ ] Release is announced where users follow the project, such as discussions, chat or social media (optional)
- [ ] Issues that are fixed in {{version}} are closed with a link to the release
- [ ] New issues are watched for the first days after the release
- [ ] Docs site is rebuilt and versioned docs for {{version}} are published (optional)

Start this checklist from your pipeline

When a v* tag is pushed, POST /api/v1/runs with template "Publish {{package}} {{version}}" and the tag without the v as version.

curl -X POST https://runbook.metastic.ch/api/v1/runs \
  -H "Authorization: Bearer $RUNBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "Publish {{package}} {{version}}", "variables": {"package": "…", "version": "…"}}'

See the API and the GitHub Action

Frequently asked questions

How do I choose the next version number?

Follow semantic versioning. If any public behaviour changes in a way that can break users, bump the major version. For new backwards-compatible features bump the minor version, and for bug fixes only bump the patch version. Before 1.0, many projects treat minor versions as breaking, so document what your project does.

Can I unpublish or replace a bad npm release?

npm only allows unpublishing under limited conditions, and you can never reuse the same version number. The usual fix is to publish a new patch version and deprecate the broken one with npm deprecate, which shows a warning to anyone who installs it. PyPI and other registries work in a similar way with yanking.

Should I publish packages from CI or from my machine?

From CI. A pipeline publish is reproducible, does not depend on one person's laptop, and can use short-lived credentials through trusted publishing. Registries such as npm and PyPI can also record provenance, which lets users verify where a package was built.

Updated 2026-11-04