kubo/docs/RELEASE_CHECKLIST.md

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

Labels

If an item should be executed only for a specific release type, it is labeled with:

• execute ONLY when releasing a Release Candidate
• execute ONLY when releasing a Final Release
• do NOT execute when releasing a Patch Release

Otherwise, it means a step should be executed for ALL release types.

Before the release

This section covers tasks to be done ahead of the release.

• Verify you have access to all the services and tools required for the release
  • GPG signature configured in local git and in GitHub
  • docker installed on your system
  • npm installed on your system
  • kubo checked out under $(go env GOPATH)/src/github.com/ipfs/kubo
    • you can also symlink your clone to the expected location by running mkdir -p $(go env GOPATH)/src/github.com/ipfs && ln -s $(pwd) $(go env GOPATH)/src/github.com/ipfs/kubo
• Upgrade Go used in CI to the latest patch release available at https://go.dev/dl/

The release

This section covers tasks to be done during each release.

1. Prepare release branch

• Prepare the release branch and update version numbers accordingly
  • create a new branch release-vX.Y.Z
    • use master as base if Z == 0
    • use release as base if Z > 0
  • update the CurrentVersionNumber in version.go in the master branch to vX.Y+1.0-dev (example)
  • update the CurrentVersionNumber in version.go in the release-vX.Y.Z branch to vX.Y.Z(-rcN) (example)
  • create a draft PR from release-vX.Y.Z to release (example)
  • Cherry-pick commits from master to the release-vX.Y.Z using git cherry-pick -x <commit> (example)
    • NOTE: cherry-picking with -x is important
  • verify all CI checks on the PR from release-vX.Y.Z to release are passing
  • Replace the Changelog and Contributors sections of the changelog with the stdout (do NOT copy the stderr) of ./bin/mkreleaselog.
    • NOTE: mkreleaselog expects your $GOPATH/src/github.com/ipfs/kubo to include latest commits from release-vX.Y.Z
  • Merge the PR from release-vX.Y.Z to release using the Create a merge commit
    • do NOT use Squash and merge nor Rebase and merge because we need to be able to sign the merge commit
    • do NOT delete the release-vX.Y.Z branch

2. Tag release

• Create the release tag
  • ⚠️ NOTE: This is a dangerous operation! Go and Docker publishing are difficult to reverse! Have the release reviewer verify all the commands marked with !
  • tag the HEAD commit using git tag -s vX.Y.Z(-rcN) -m 'Prerelease X.Y.Z(-rcN)'
  • tag the HEAD commit of the release branch using git tag -s vX.Y.Z -m 'Release X.Y.Z'
  • ⚠️ verify the tag is signed and tied to the correct commit using git show vX.Y.Z(-rcN)
  • push the tag to GitHub using git push origin vX.Y.Z(-rcN)
    • ⚠️ do NOT use git push --tags because it pushes all your local tags

3. Publish

• Publish Docker image to DockerHub
  • Wait for Publish docker image workflow run initiated by the tag push to finish
  • verify the image is available on Docker Hub → tags
• Publish the release to dist.ipfs.tech
  • check out ipfs/distributions
  • create new branch: run git checkout -b release-kubo-X.Y.Z(-rcN)
  • Verify ipfs/distributions's .tool-versions's golang entry is set to the latest go release on the major go branch Kubo is being tested on (see go-version:). If not, update .tool-versions to match the latest golang.
  • run ./dist.sh add-version kubo vX.Y.Z(-rcN) to add the new version to the versions file (usage)
  • create and merge the PR which updates dists/kubo/versions (NOTE: will also have dists/kubo/current – example)
  • wait for the CI workflow run initiated by the merge to master to finish
  • verify the release is available on dist.ipfs.tech
• Publish the release to NPM
  • manually dispatch the Release to npm workflow if it was not executed already and verify it discovered the new release
  • verify the release is available on NPM
• Publish the release to GitHub kubo/releases
  • create a new release
    • RC example
    • FINAL example
    • use the vX.Y.Z(-rcN) tag
    • link to the release issue
    • link to the changelog in the description
    • check the This is a pre-release checkbox
    • copy the changelog (without the header) in the description
    • do NOT check the This is a pre-release checkbox
  • run the sync-release-assets workflow and verify the release assets are attached to the GitHub release

4. After Publishing

• Merge the release branch back into master
  • Create a new branch merge-release-vX.Y.Z from release
  • Create the next ./docs/changelogs/vA.B.md and link to the new changelog from the ./CHANGELOG.md file
  • Create and merge a PR from merge-release-vX.Y.Z to master
    • ⚠️ do NOT use Squash and merge nor Rebase and merge because we need to be able to sign the merge commit
    • ⚠️ NOTE: make sure to ignore the changes to version.go (keep the -dev in master)
• Update ipshipyard/waterworks-infra
  • Update Kubo staging environment, see the Running Kubo tests on staging for details.
    • Test last release against the current RC
    • Test last release against the current one
  • Update collab cluster boxes to the tagged release (final or RC)
  • Update libp2p bootstrappers to the tagged release (final or RC)
• Promote the release
  • create an IPFS Discourse topic (prerelease example, release example)
    • use Kubo vX.Y.Z(-rcN) is out! as the title and kubo as tags
    • repeat the title as a heading (##) in the description
    • link to the GitHub Release, binaries on IPNS, docker pull command and release notes in the description
    • pin the IPFS Discourse topic globally, you can make the topic a banner if there is no banner already
  • verify the IPFS Discourse topic was copied to:
    • #ipfs-chatter in IPFS Discord
    • #ipfs-chatter in FIL Slack
    • #ipfs-chatter:ipfs.io in Matrix
  • Add the link to the IPFS Discourse topic to the GitHub Release description (example)
  • create an issue comment mentioning early testers on the release issue (example)
  • create an issue comment linking to the release on the release issue (example)
  • promote on bsky.app (example)
  • promote on x.com (example)
  • post the link to the GitHub Release to Reddit (example)
• Manually smoke-test the new version with IPFS Companion Browser Extension
• Update Kubo in ipfs-desktop
  • create a PR which updates kubo version to the tagged version in package.json and package-lock.json
  • switch to final release and merge
• Update Kubo docs at docs.ipfs.tech:
  • run the update-on-new-ipfs-tag.yml workflow
  • merge the PR created by the update-on-new-ipfs-tag.yml workflow run
• Create a blog entry on blog.ipfs.tech
  • create a PR which adds a release note for the new Kubo version (example)
  • merge the PR
  • verify the blog entry was published
• Create a dependency update PR
  • check out ipfs/kubo
  • go over direct dependencies from go.mod in the root directory (NOTE: do not run go get -u as it will upgrade indirect dependencies which may cause problems)
  • run make mod_tidy
  • create a PR which updates go.mod and go.sum
  • add the PR to the next release milestone
• Create the next release issue
• Close the release issue