Releasing a Library with Automated Versioning

A library on npm or PyPI has reached the point where hand-cut releases hurt. The ritual — bump the version in package.json, write changelog entries from memory, tag, push, publish — is tedious enough that releases bunch up, and tedious enough that someone eventually forgets a step and ships a version whose tag and published artifact disagree. The fix is to make the release a consequence of merging, not a separate chore: the commit messages drive the version bump, a tool writes the changelog and tag, and an Action publishes to the registry.

The decisions this forces are about contracts. The commit message becomes machine-readable input, so its format is now load-bearing. The choice of release tool depends on whether you have one package or many. And the publish credential — historically a long-lived registry token that anyone who steals it can publish under your name — becomes the highest-value secret in the repo, which is exactly why it should stop being a stored secret at all.

Conventional Commits as the Contract

The version bump is computed from commit prefixes: fix: yields a patch, feat: yields a minor, and a BREAKING CHANGE: footer yields a major. The commit message is no longer just a note to future readers — it is the input that decides what SemVer number ships, so it has to be correct. A commitlint check on PRs enforces the format before anything merges, rejecting a message the release tool would misread.

feat: add streaming parser API

BREAKING CHANGE: parse() now returns a stream, not a string

semantic-release vs Changesets

Two tools dominate, and they embody different philosophies. semantic-release is fully automated: merge to main, it reads the commits since the last tag, computes the version, and publishes — no human in the loop. Changesets takes the opposite stance: a contributor adds a changeset file in the PR describing the bump, that file is reviewed alongside the code, and the release is assembled from accumulated changesets. For a single package, semantic-release's automation is the win. For a monorepo where packages version independently, Changesets is the better fit because it tracks per-package bumps that one commit-stream cannot express.

The Release Pipeline

On merge to main, the pipeline computes the next version, writes the changelog, creates the git tag and a GitHub Release, then triggers the publish. The crucial structural rule is that publishing runs only on main after CI passes — never on a PR trigger, where untrusted contributor code could run alongside the publish credential.

on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # full history for version computation
      - run: npx semantic-release

Publishing With OIDC Trusted Publishing

Both npm and PyPI now accept short-lived OIDC tokens minted by Actions, which removes the standing NPM_TOKEN or PyPI API token from the repo's secrets entirely. The job requests an ID token, the registry verifies it came from this repo's workflow, and the publish proceeds with a credential that never existed before the run and is useless after it. As a bonus, the registry records build provenance, so consumers can verify the package was built where it claims.

    permissions:
      id-token: write    # OIDC trusted publishing, no stored token
      contents: write    # create the tag and GitHub Release
    steps:
      - uses: actions/setup-node@v4
        with: { registry-url: 'https://registry.npmjs.org' }
      - run: npm publish

Pre-releases and Channels

A breaking change does not have to land on everyone at once. Publishing to a next or beta dist-tag, or versioning as 1.0.0-rc.1, lets willing consumers opt into unreleased code while the default install stays on the stable line. This is how you get real-world testing of a major version before you make it the default and break every caret-ranged dependent.

Failure and Idempotency

The ugly failure is a half-published release: the tag and GitHub Release got created, then the registry push failed. Recovering means not double-publishing the same version, since registries reject a re-publish of an existing version and a forced one would break anyone who already pulled it. The pipeline has to be safe to re-run — detect that the version is already published and skip, or fail loudly rather than minting a second tag for the same release.