Release 0.38

[lidel]

Part of ongoing maintenance of key libraries and services ipshipyard/roadmaps#1 and ipshipyard/roadmaps#6

Meta

• Release owner: @lidel
• Release reviewer/backup: @gammazero
• Expected RC1 date: TBD
• 🚢 Expected final release date: TBD
• Release PR: chore: release v0.38.0 #10978
• Accompanying PR for improving the release process: TBD
• Internal Staging tests by Shipyard: notion: /Kubo-0-37-vs-0-38
• Changelog: https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.38.md

Items In Scope

Required

• Improved debugging facilities — IPFS/2025 ipshipyard/roadmaps#11
  • feat: ipfs-webui v4.9.0 with retrieval diagnostics #10969 with feat: add diagnostics screen ipfs-webui#2392
• Most Kubo users can reliably advertise their data into the Amino DHT — IPFS/2025 ipshipyard/roadmaps#7
  • Integrate Modernized Provider System from go-libp2p-kad-dht #10881
    • feat: opt-in new Sweep provide system #10834
    • migration to Move Reprovider config to Provider #10909
      • refactor(config): migration 17-to-18 to unify Provider/Reprovider into Provide.DHT #10951
    • TODO changelog: document the dht put metric name total_provide_count (figure full name)
• Update error pages on the gateways to surface debugging information — IPFS/2025 ipshipyard/roadmaps#14 (put/get extra info from routing/bitswap)
  • feat(gateway): improved error page with retrieval state details #10950 with boxo that includes:
    • feat(gateway): add retrieval state tracking for timeout diagnostics boxo#1015
    • feat(gateway): enhance 504 timeout errors with diagnostic UX boxo#1023
• Node telemetry — IPFS/2025 ipshipyard/roadmaps#17
  • fix(telemetry): improve vm/container detection #10944
• enable riscv64 builds on dist.ipfs.tech (close RISC-V Support #8398)
• fix: ipfs pin ls <cid> --names #10970
  • needs boxo with feat(pinner): add CheckIfPinnedWithType for efficient checks with names boxo#1035
  • needs boxo with fix(pinner): restore indirect pin detection and add context cancellation boxo#1039
  • kubo-rpc-client for JS: feat: add pin name support js-kubo-rpc-client#343
• Fix unbound MFS growth on mutating without flush
  • fix(mfs): unbound cache growth with flush=false #10971

Found during RC1

• chore: update boxo and kad-dht dependencies #10995
• 0.38.0-rc1: slow daemon start with Provide.DHT.SweepEnabled #10979 → fix in fix: SweepingProvider slow start  #10980
• webui: "Check Retrieval" sometimes opens log instead of the right tab
  • fix in fix: prevent redirect when navigating to retrieval-check ipfs-webui#2439
  • fix: update webui to v4.9.1 #10994
• fix: limit pin names to 255 bytes #10981
• fix(mfs): add soft limit for --flush=false #10985
  • boxo with revert: remove MFS auto-flush mechanism boxo#1041
• dht/provider: remove the cleanup of persisted keystore on shutdown (we dont want to block shutdown/restart operation for too long when kubo is orchestrated by docker etc) - handled in fix: SweepingProvider slow start  #10980
• ERROR dht/provider provider/provider.go:665 coveredPrefixLen==0, coveredPrefixStack [10 11001] → fix in refactor(provider): closestPeerToPrefix coverage trie libp2p/go-libp2p-kad-dht#1156
• Crash when pebble is used in keystore → fix in fix(keystore): use new batch after commit libp2p/go-libp2p-kad-dht#1154
• StartProviding() silently fails soon after daemon start: LAN provider: provider: offline #10988 → fix in fix: provider merge conflicts #10989
• kad-dht with
  • fix(keystore): use new batch after commit libp2p/go-libp2p-kad-dht#1154
  • refactor(provider): closestPeerToPrefix coverage trie libp2p/go-libp2p-kad-dht#1156
• Filestore providing fix: 0.38.0-rc1 Provide.DHT.SweepEnabled=True doesn't announce filestore (--no-copy) data #10983
  • Filestore: add Provider option to provide filestore blocks. boxo#1042
  • fix: provide Filestore nodes #10990
• provider offline with Sweep = true when providing (adding something) right after start: StartProviding() silently fails soon after daemon start: LAN provider: provider: offline #10988

Nice To Have (Optional)

• fix(cmds): cleanup unicode identify strings #9465
• boxo with feat(routing/http): return 200 for empty results per IPIP-513 boxo#1032
• boxo with fix(verifcid): enforce size limit for identity CIDs boxo#1018
• chore: update boxo for retrieval timeout diagnostics #10939
  • boxo with feat(gateway): add retrieval state tracking for timeout diagnostics boxo#1015
• nat: stuck in error loop after router restart libp2p/go-libp2p#3224
• feat: optimize docker builds #10925
• repo: use config api to get node root path #10934
• config option to disable automatic providing #3480

[lidel]

✅ Release Checklist (v0.38.0-rc1)

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:
  • Update version.go to vX.Y+1.0-dev (⚠️ double-check Y+1 is correct) (example PR)
  • Create ./docs/changelogs/vX.Y+1.md and add link in CHANGELOG.md
• 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)
• In release-vX.Y.Z branch, cherry-pick commits from master: git cherry-pick -x <commit> (example)
  • ⚠️ NOTE: -x flag records original commit SHA for traceability and ensures cleaner merges with deduplicated commits in history
• Verify all CI checks on the PR are passing
• FINAL only: In release-vX.Y.Z branch, replace Changelog and Contributors sections 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 because we need to be able to sign 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 reversed!
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 because it pushes all your local tags
• STOP: Wait for Docker build to complete before proceeding

Publish Artifacts

• Docker: Publish to DockerHub
  • Wait for Publish docker image workflow triggered by tag push
  • Verify 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
  • 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: make sure to ignore the changes to version.go (keep the -dev in master)
  • 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 because we want to preserve original commit history
• Update ipshipyard/waterworks-infra
  • Update Kubo staging environment (Running Kubo tests on staging)
    • RC: Test last release against current RC
    • FINAL: Test last release against current one
  • Update collab cluster boxes to the tagged release
  • Update libp2p bootstrappers to the tagged release
• Smoke test with IPFS Companion Browser Extension
• Update ipfs-desktop
  • Create PR updating kubo version in package.json and package-lock.json
  • FINAL only: Merge and create/request new release
• FINAL only: Update docs.ipfs.tech: run update-on-new-ipfs-tag.yml workflow and merge the PR

Promotion

• Create IPFS Discourse topic (RC example, FINAL example)
  • Title: Kubo vX.Y.Z(-rcN) is out!, tag: kubo
  • Use title as heading (##) in description
  • Include: GitHub release link, IPNS binaries, docker pull command, release notes
  • Pin topic globally (make banner if no existing banner)
• Verify bot posted to #ipfs-chatter (Discord) or #ipfs-chatter:ipfs.io (Matrix)
• RC only: Comment on release issue mentioning early testers (example)
• FINAL only: Comment on release issue with link (example)
• FINAL only: Create blog.ipfs.tech entry (example)
• FINAL non-PATCH: (optional) Post on social media (bsky, x.com, Reddit)

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

[lidel]

✅ Release Checklist (v0.38.0-rc2)

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:
  • Update version.go to vX.Y+1.0-dev (⚠️ double-check Y+1 is correct) (example PR)
  • Create ./docs/changelogs/vX.Y+1.md and add link in CHANGELOG.md
• 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)
• In release-vX.Y.Z branch, cherry-pick commits from master: git cherry-pick -x <commit> (example)
  • ⚠️ NOTE: -x flag records original commit SHA for traceability and ensures cleaner merges with deduplicated commits in history
• Verify all CI checks on the PR are passing
• FINAL only: In release-vX.Y.Z branch, replace Changelog and Contributors sections 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 because we need to be able to sign 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 reversed!
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 because it pushes all your local tags
• STOP: Wait for Docker build to complete before proceeding

Publish Artifacts

• Docker: Publish to DockerHub
  • Wait for Publish docker image workflow triggered by tag push
  • Verify 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
  • 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: make sure to ignore the changes to version.go (keep the -dev in master)
  • 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 because we want to preserve original commit history
• Update ipshipyard/waterworks-infra
  • Update Kubo staging environment (Running Kubo tests on staging)
    • RC: Test last release against current RC
    • FINAL: Test last release against current one
  • Update collab cluster boxes to the tagged release
  • Update libp2p bootstrappers to the tagged release
• Smoke test with IPFS Companion Browser Extension
• Update ipfs-desktop
  • Create PR updating kubo version in package.json and package-lock.json
  • FINAL only: Merge and create/request new release
• FINAL only: Update docs.ipfs.tech: run update-on-new-ipfs-tag.yml workflow and merge the PR

Promotion

• Create IPFS Discourse topic (RC example, FINAL example)
  • Title: Kubo vX.Y.Z(-rcN) is out!, tag: kubo
  • Use title as heading (##) in description
  • Include: GitHub release link, IPNS binaries, docker pull command, release notes
  • Pin topic globally (make banner if no existing banner)
• Verify bot posted to #ipfs-chatter (Discord) or #ipfs-chatter:ipfs.io (Matrix)
• RC only: Comment on release issue mentioning early testers (example)
• FINAL only: Comment on release issue with link (example)
• FINAL only: Create blog.ipfs.tech entry (example)
• FINAL non-PATCH: (optional) Post on social media (bsky, x.com, Reddit)

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