Release 0.40

[lidel]

Note

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: Feb 12th
• 🚢 Expected final release date: Feb 17th
• Release PR: Release v0.40.0 #11194
• Accompanying PR for improving the release process: docs: streamline release checklist ordering and dependencies #11193
• Internal Staging tests by Shipyard: (internal)
• Changelog: https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.40.md

Items In Scope

Cherry-pick for RC2 / final

• Upgrade to Boxo v0.37.0 #11201
• kad-dht bump to v0.38 in fix(deps): bump go-libp2p-kad-dht to latest master #11196
• upgrade to go-ipfs-cmds v0.16.0 #11202
• fix: improve ipfs name put for IPNS record republishing #11199
• fix: update webui to v4.11.1 #11204
  • fix(peers): accept /p2p/ prefix in peer filter input ipfs-webui#2475
  • feat/fix: keyboard shortcuts for search/filter inputs ipfs-webui#2476
  • fronted(modal): fix the position of modal overlay ipfs-webui#2473

Required

• fix(deps): bump go-libp2p-kad-dht to latest master #11196
• chore: update to latest boxo #11195
• invalid memory address or nil pointer dereference #11116
• test: IPIP-523 format query precedence over Accept header #11086
• IPIP-476 feat: support GetClosesPeers (IPIP-476) and ExposeRoutingAPI by default #10954 + 179e1f8
• IPIP-0524: Remove cross-codec conversion from HTTP Gateways specs#524
• IPIP-499 Implement modern CID profile from IPIP-499 #11071
• chore: remove deprecated go-ipfs Docker image publishing #11081
• (potential bug or ux bug): investigate 1 region problem when sweep+accelerated client are enabled (internal)
• chore: update go-libp2p 0.46 #11105 with fixes by @lidel
• feat(pubsub): persistent validation and diagnostic commands #11110
• go-libp2p with fix(autonatv2): secondary addrs inherit reachability from primary libp2p/go-libp2p#3435
• go-libp2p with quic-go
  • https://github.com/quic-go/quic-go/releases/tag/v0.58.0 (optimized handshakes)
  • https://github.com/quic-go/quic-go/releases/tag/v0.58.1 (ping loop fixes)
• https://github.com/ipshipyard/waterworks-infra/issues/860
  • boxo with fix(bitswap/network): stream.Close() blocks indefinitely on unresponsive peers boxo#1083
  • (or go-libp2p with fix(basic_host): stream.Close() blocks indefinitely on unresponsive peers libp2p/go-libp2p#3448)
• DHT Sweep only sees 1 Region when Accelerated Client is enabled #11085
  • fix(provider): wait for fullrt crawl completion before providing #11137
  • feat(provider): info log AcceleratedDHTClient crawl #11143
• Do not require network i/o for *.libp2p.direct domain resolution #11136
• feat: update ipfs-webui to v4.11.0 #11182 with
  • feat: DHT Provide Sweep Diagnostic Screen ipfs-webui#2463
  • feat(files): resolve paths before inspect and support protocol URL ipfs-webui#2465
• feat: add swarm addrs autonat command #11184

Nice To Have (Optional)

Bugs

• MFS bug: ipfs files rm hanging #10842
• denylist: ?format=car does not skip directly blocked CIDs #10361
• fix(routing): use LegacyProvider for HTTP-only custom routing #11112

UX/DX Improvements

• provider keystore sync failed {"err": "keystore is closed", "strategy": "all"} #11127
• keys: skip bad keys when listing #11115
• feat(p2p): add --foreground flag to listen and forward commands #11099
• fix(cli): deduplicate dag stat blocks by multihash #11098
• feat(cli): improve ipfs dag stat output UX #11097
• feat(gateway): add default landing page when RootRedirect is not set #11091
• Improved Reprovider.Strategy for entity DAGs (HAMT/UnixFS dirs, big files) #8676
• Windows: redirect to *.ipfs.localhost fails in non-browser contexts #11024 (needs boxo fix for boxo#1054)
• ipfs get --compress gives incorrect Header #2376 (tbd if we fix or descope)
• ERROR from webrtc-transport-pion Failed to accept data channel #11053 (needs go-libp2p release with this PR)
• Move ipfs routing provide and reprovide into ipfs provide namespace #10865 (keep old cmds as deprecated)
• Add CLI timeout for retrieval/resolution #10953
• ipfs routing get should allow querying when node is offline by enabling a flag #10958
• feat(mfs): chroot command to change the root #8648 (also fix for Ipfs daemon hangs when MFS root is not available locally #7183)
• refactor: support percent-encoded /unix paths #10833
• docs: clarify Routing.Type=custom as experimental #11111
• feat(client/rpc): add provide stat and dag import support #11069

Denylist / Content Filtering

• Support consuming https://badbits.dwebops.pub/badbits.deny rainbow#126 (same applies to Kubo)
  • fix(gateway): prevent blocked CIDs in CAR responses #10948
    • ipfs blockservice is incompatible with sessions ipfs-shipyard/nopfs#34 (re-triage once kubo#10948 is done)
  • HTTPSubscriber: check with If-None-Match or If-Modified-Since ipfs-shipyard/nopfs#38
  • HTTPSubscriber: detect when list is not append-only ipfs-shipyard/nopfs#39
• TBD: consider porting URLhaus from feat: add IP denylist plugin for abuse prevention ipshipyard/p2p-forge#79 for phishing prevention
• Blocks are only sanity checked when debug mode is active #1152

Dependencies / Infrastructure

• refactor: rewrite batch mode to use temp directory go-ds-flatfs#142
• chore: golangci/v2 with go 1.25 support #10924
• Update pubsub and add default validator #9684 (status/blocked)
• fix(mdns): filter addresses to reduce packet size libp2p/go-libp2p#3434

TBD (Things we need to re-triage)

• provider: duplicated CIDs sent to provide queue boxo#901 (TBD)
• fix(ipfswatch): loading datastore plugins #11078

[lidel]

✅ Release Checklist v0.40.0-rc1

Release type: RC (Release Candidate)

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: Latest release on both boxes
  • FINAL: Update collab cluster boxes to the tagged release
  • FINAL: 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: 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

• 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