ContextQMD
Back to Kubo

✅ Release Checklist (vX.Y.Z[-rcN])

docs/RELEASE_CHECKLIST.md

0.41.09.0 KB
Original Source
<!-- Last updated during [v0.40.0 release](https://github.com/ipfs/kubo/issues/11008) -->

✅ Release Checklist (vX.Y.Z[-rcN])

Release types: RC (Release Candidate) | FINAL | PATCH

Prerequisites

  • GPG signature configured in local git and GitHub
  • Docker installed on your system
  • npm installed on your system
  • kubo repository cloned locally
  • non-PATCH: Upgrade Go in CI to latest patch from https://go.dev/dl/

1. Prepare Release Branch

  • Fetch latest changes: git fetch origin master release
  • Create branch release-vX.Y.Z (base from: master if Z=0 for new minor/major, release if Z>0 for patch)
  • RC1 only: Switch to master branch and prepare for next release cycle:
  • Switch to release-vX.Y.Z branch and update version.go to vX.Y.Z(-rcN) (⚠️ double-check Y matches release) (example)
  • Create draft PR: release-vX.Y.Z → release (example)
  • Cherry-pick commits from master into release-vX.Y.Z: git cherry-pick -x <commit> (example)
    • ⚠️ NOTE: -x flag records original commit SHA for traceability and cleaner merge history
  • Verify all CI checks on the PR are passing
  • FINAL only: Replace Changelog and Contributors sections in release-vX.Y.Z with ./bin/mkreleaselog stdout (do NOT copy stderr)
  • FINAL only: Merge PR (release-vX.Y.Z → release) using Create a merge commit
    • ⚠️ do NOT use Squash and merge nor Rebase and merge; we want the releaser's GPG signature on the merge commit
    • ⚠️ do NOT delete the release-vX.Y.Z branch (needed for future patch releases and git history)

2. Tag & Publish

Create Tag

⚠️ POINT OF NO RETURN: once pushed, tags trigger automatic Docker/NPM publishing that cannot be undone! If you're making a release for the first time, do pair programming and have the release reviewer verify all commands.

  • RC: From release-vX.Y.Z branch: git tag -s vX.Y.Z-rcN -m 'Prerelease X.Y.Z-rcN'
  • FINAL: After PR merge, from release branch: git tag -s vX.Y.Z -m 'Release X.Y.Z'
  • ⚠️ Verify tag is signed and correct: git show vX.Y.Z(-rcN)
  • Push tag: git push origin vX.Y.Z(-rcN)
    • ⚠️ do NOT use git push --tags (pushes every local tag, cluttering the repo)
  • STOP: Wait for Docker build to complete before proceeding

Publish Artifacts

Parallelism: Docker and dist.ipfs.tech only depend on the pushed tag and can be started in parallel. NPM and GitHub Release both depend on dist.ipfs.tech completing first.

  • Docker: Verify docker-image CI passed and image is available on Docker Hub → tags
  • dist.ipfs.tech: Publish to dist.ipfs.tech
    • Check out ipfs/distributions
    • Create branch: git checkout -b release-kubo-X.Y.Z(-rcN)
    • Verify .tool-versions golang matches Kubo's CI go-version: (update if needed)
    • Run: ./dist.sh add-version kubo vX.Y.Z(-rcN) (usage)
    • Create and merge PR (updates dists/kubo/versions, FINAL also updates dists/kubo/current - example)
    • Wait for CI workflow triggered by merge
    • Verify release on dist.ipfs.tech
  • NPM: Publish to NPM
    • Manually dispatch Release to npm workflow if not auto-triggered
    • Verify release on NPM
  • GitHub Release: Publish to GitHub
    • Create release (RC example, FINAL example)
    • Use tag vX.Y.Z(-rcN)
    • Link to release issue
    • RC: Link to changelog, check This is a pre-release
    • FINAL: Copy changelog content (without header), do NOT check pre-release
    • Run sync-release-assets workflow (requires dist.ipfs.tech)
    • Verify assets are attached to the GitHub release

3. Post-Release

Technical Tasks

  • FINAL only: Merge release → master
    • Create branch merge-release-vX.Y.Z from release
    • Merge master to merge-release-vX.Y.Z first, and resolve conflict in version.go
      • ⚠️ NOTE: keep the -dev version from master in version.go, discard version from release
    • Create and merge PR from merge-release-vX.Y.Z to master using Create a merge commit
      • ⚠️ do NOT use Squash and merge nor Rebase and merge; only Create a merge commit preserves commit history and the audit trail of what was merged where
  • Update ipshipyard/waterworks-infra
    • Update Kubo staging environment (Running Kubo tests on staging)
      • RC: Test last release against current RC
      • FINAL: Latest release on both boxes
    • FINAL: Update collab cluster boxes to the tagged release
    • FINAL: Update libp2p bootstrappers to the tagged release
  • Update ipfs-desktop
    • Create PR updating kubo version in package.json and package-lock.json
    • Smoke test with IPFS Companion Browser Extension against the PR build
    • FINAL: Merge PR and ship new ipfs-desktop release
  • FINAL only: Update docs.ipfs.tech: run update-on-new-ipfs-tag.yml workflow and merge the PR

Promotion

Final Steps

  • FINAL non-PATCH: Create dependency update PR
    • Review direct dependencies from root go.mod (⚠️ do NOT run go get -u as it will upgrade indirect dependencies which may cause problems)
    • Run make mod_tidy
    • Create PR with go.mod and go.sum updates
    • Add PR to next release milestone
  • FINAL non-PATCH: Create next release issue (example)
  • FINAL only: Close release issue