docs: streamline release checklist ordering and dependencies (#11193)
* docs: streamline release checklist ordering and dependencies - add parallelism note clarifying artifact dependency graph - deduplicate Docker wait (STOP gate covers it) - note sync-release-assets dependency on dist.ipfs.tech - move Companion smoke test into ipfs-desktop step (test against PR build) * docs: improve release checklist clarity and conciseness - front-load verbs in checklist items (action before location) - tighten warning text with clear rationale (GPG signatures, audit trail) - fix passive voice, cut filler phrases - clarify version.go conflict resolution during merge-back
Marcin Rataj committed
Feb 26, 2026 at 00:53 UTC
24038c30cfa2258f80e0fe5c7ce31311843481e5
1 file changed
+15
-14
docs/RELEASE_CHECKLIST.md
+15
-14
@@ -1,4 +1,4 @@
1
-<!-- Last updated during [v0.38.0 release](https://github.com/ipfs/kubo/issues/10884) -->
1
+<!-- Last updated during [v0.40.0 release](https://github.com/ipfs/kubo/issues/11008) -->
2
3
# ✅ Release Checklist (vX.Y.Z[-rcN])
4
@@ -21,32 +21,33 @@
21
- [ ] Create `./docs/changelogs/vX.Y+1.md` and add link in [CHANGELOG.md](https://github.com/ipfs/kubo/blob/master/CHANGELOG.md)
22
- [ ] Switch to `release-vX.Y.Z` branch and update [version.go](https://github.com/ipfs/kubo/blob/master/version.go) to `vX.Y.Z(-rcN)` (⚠️ double-check Y matches release) ([example](https://github.com/ipfs/kubo/pull/9394))
23
- [ ] Create draft PR: `release-vX.Y.Z` → `release` ([example](https://github.com/ipfs/kubo/pull/9306))
24
-- [ ] In `release-vX.Y.Z` branch, cherry-pick commits from `master`: `git cherry-pick -x <commit>` ([example](https://github.com/ipfs/kubo/pull/10636/commits/033de22e3bc6191dbb024ad6472f5b96b34e3ccf))
25
- - ⚠️ **NOTE:** `-x` flag records original commit SHA for traceability and ensures cleaner merges with deduplicated commits in history
24
+- [ ] Cherry-pick commits from `master` into `release-vX.Y.Z`: `git cherry-pick -x <commit>` ([example](https://github.com/ipfs/kubo/pull/10636/commits/033de22e3bc6191dbb024ad6472f5b96b34e3ccf))
25
+ - ⚠️ **NOTE:** `-x` flag records original commit SHA for traceability and cleaner merge history
26
- [ ] Verify all CI checks on the PR are passing
27
-- [ ] **FINAL only:** In `release-vX.Y.Z` branch, replace `Changelog` and `Contributors` sections with `./bin/mkreleaselog` stdout (do **NOT** copy stderr)
27
+- [ ] **FINAL only:** Replace `Changelog` and `Contributors` sections in `release-vX.Y.Z` with `./bin/mkreleaselog` stdout (do **NOT** copy stderr)
28
- [ ] **FINAL only:** Merge PR (`release-vX.Y.Z` → `release`) using `Create a merge commit`
29
- - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge` because we need to be able to sign the merge commit
29
+ - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge` -- we want the releaser's GPG signature on the merge commit
30
- ⚠️ do **NOT** delete the `release-vX.Y.Z` branch (needed for future patch releases and git history)
31
32
## 2. Tag & Publish
33
34
### Create Tag
35
-⚠️ **POINT OF NO RETURN:** Once pushed, tags trigger automatic Docker/NPM publishing that cannot be reversed!
35
+⚠️ **POINT OF NO RETURN:** Once pushed, tags trigger automatic Docker/NPM publishing and are irreversible!
36
If you're making a release for the first time, do pair programming and have the release reviewer verify all commands.
37
38
- [ ] **RC:** From `release-vX.Y.Z` branch: `git tag -s vX.Y.Z-rcN -m 'Prerelease X.Y.Z-rcN'`
39
- [ ] **FINAL:** After PR merge, from `release` branch: `git tag -s vX.Y.Z -m 'Release X.Y.Z'`
40
- [ ] ⚠️ Verify tag is signed and correct: `git show vX.Y.Z(-rcN)`
41
- [ ] Push tag: `git push origin vX.Y.Z(-rcN)`
42
- - ⚠️ do **NOT** use `git push --tags` because it pushes all your local tags
42
+ - ⚠️ do **NOT** use `git push --tags` (pushes all local tags, polluting the repo with noise)
43
- [ ] **STOP:** Wait for [Docker build](https://github.com/ipfs/kubo/actions/workflows/docker-image.yml) to complete before proceeding
44
45
### Publish Artifacts
46
47
-- [ ] **Docker:** Publish to [DockerHub](https://hub.docker.com/r/ipfs/kubo/tags)
48
- - [ ] Wait for [Publish docker image](https://github.com/ipfs/kubo/actions/workflows/docker-image.yml) workflow triggered by tag push
49
- - [ ] Verify image is available on [Docker Hub → tags](https://hub.docker.com/r/ipfs/kubo/tags)
47
+> **Parallelism:** Docker and dist.ipfs.tech only depend on the pushed tag and can be started in parallel.
48
+> NPM and GitHub Release both depend on dist.ipfs.tech completing first.
49
+
50
+- [ ] **Docker:** Verify [docker-image CI](https://github.com/ipfs/kubo/actions/workflows/docker-image.yml) passed and image is available on [Docker Hub → tags](https://hub.docker.com/r/ipfs/kubo/tags)
51
- [ ] **dist.ipfs.tech:** Publish to [dist.ipfs.tech](https://dist.ipfs.tech)
52
- [ ] Check out [ipfs/distributions](https://github.com/ipfs/distributions)
53
- [ ] Create branch: `git checkout -b release-kubo-X.Y.Z(-rcN)`
@@ -64,7 +65,7 @@ If you're making a release for the first time, do pair programming and have the
65
- [ ] Link to release issue
66
- [ ] **RC:** Link to changelog, check `This is a pre-release`
67
- [ ] **FINAL:** Copy changelog content (without header), do **NOT** check pre-release
67
- - [ ] Run [sync-release-assets](https://github.com/ipfs/kubo/actions/workflows/sync-release-assets.yml) workflow
68
+ - [ ] Run [sync-release-assets](https://github.com/ipfs/kubo/actions/workflows/sync-release-assets.yml) workflow (requires dist.ipfs.tech)
69
- [ ] Verify assets are attached to the GitHub release
70
71
## 3. Post-Release
@@ -74,18 +75,18 @@ If you're making a release for the first time, do pair programming and have the
75
- [ ] **FINAL only:** Merge `release` → `master`
76
- [ ] Create branch `merge-release-vX.Y.Z` from `release`
77
- [ ] Merge `master` to `merge-release-vX.Y.Z` first, and resolve conflict in `version.go`
77
- - ⚠️ **NOTE:** make sure to ignore the changes to [version.go](https://github.com/ipfs/kubo/blob/master/version.go) (keep the `-dev` in `master`)
78
+ - ⚠️ **NOTE:** keep the `-dev` version from `master` in [version.go](https://github.com/ipfs/kubo/blob/master/version.go), discard version from `release`
79
- [ ] Create and merge PR from `merge-release-vX.Y.Z` to `master` using `Create a merge commit`
79
- - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge` because we want to preserve original commit history
80
+ - ⚠️ do **NOT** use `Squash and merge` nor `Rebase and merge` -- only `Create a merge commit` preserves commit history and audit trail of what was merged where
81
- [ ] Update [ipshipyard/waterworks-infra](https://github.com/ipshipyard/waterworks-infra)
82
- [ ] Update Kubo staging environment ([Running Kubo tests on staging](https://www.notion.so/Running-Kubo-tests-on-staging-488578bb46154f9bad982e4205621af8))
83
- [ ] **RC:** Test last release against current RC
84
- [ ] **FINAL:** Latest release on both boxes
85
- [ ] **FINAL:** Update collab cluster boxes to the tagged release
86
- [ ] **FINAL:** Update libp2p bootstrappers to the tagged release
86
-- [ ] Smoke test with [IPFS Companion Browser Extension](https://docs.ipfs.tech/install/ipfs-companion/)
87
- [ ] Update [ipfs-desktop](https://github.com/ipfs/ipfs-desktop)
88
- [ ] Create PR updating kubo version in `package.json` and `package-lock.json`
89
+ - [ ] Smoke test with [IPFS Companion Browser Extension](https://docs.ipfs.tech/install/ipfs-companion/) against the PR build
90
- [ ] **FINAL:** Merge PR and ship new ipfs-desktop release
91
- [ ] **FINAL only:** Update [docs.ipfs.tech](https://docs.ipfs.tech/): run [update-on-new-ipfs-tag.yml](https://github.com/ipfs/ipfs-docs/actions/workflows/update-on-new-ipfs-tag.yml) workflow and merge the PR
92