Release 0.39

[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: 2025-11-17
• 🚢 Expected final release date: TBD (~Nov 26th or 27th if no issues)
• Release PR: Release v0.39.0 #11064
• Accompanying PR for improving the release process: TBD
• Internal Staging tests by Shipyard: notion (private)
• Changelog: https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.39.md

Items In Scope

Required

• Integrate Modernized Provider System from go-libp2p-kad-dht #10881

  • Provide.DHT.SweepEnabled=true by default
    • feat: enable DHT Provide Sweep by default #10955
  • resume interrupted reprovide (depends on provider: resume reprovide operations libp2p/go-libp2p-kad-dht#1159 & feat(provider): resume reprovides libp2p/go-libp2p-kad-dht#1170)
  • feat(provide): detailed ipfs provide stat  #11019
  • config: increase default Provide.DHT.MaxProvideConnsPerWorker #11016
  • sweep: slow reprovide alerts #11021
  • refactor(keystore): track size libp2p/go-libp2p-kad-dht#1181
  • Decrease Time for Root CID Availability 10x on ipfs add #11015
    • feat(cli/rpc/add): fast provide of root CID #11046 (ipfs add --fast-provide-root)
    • feat: fast provide support in dag import #11058 (ipfs dag import --fast-provide-root)
  • docs: clarify provide stats metric types and calculations #11041
  • panic in provide system near deque.(*Deque[...]).PushBack #11047
  • Add telemetry data for provide system #11055
  • telemetry: collect high level provide DHT sweep settings #11056

• feat: add docker stub for deprecated ipfs/go-ipfs name #10998

• go-libp2p with NAT fix https://github.com/libp2p/go-libp2p/releases/tag/v0.44.0

  • document fix: self-healing NAT mappings with request deduplication libp2p/go-libp2p#3367 in changelog
  • merge fix: go-libp2p v0.44 with self-healing UPnP port mappings #11032
  • document RISC-V support while at it

• chore: go-libp2p-kad-dht patch #11012

• new commands have good UX

  • updated go kubo-rpc-client
  • updated js kubo-rpc-client

• fix traces related to bitswap

  • bitswap/session: context-aware lifecycle boxo#1052
  • bitswap: link traces boxo#1053
  • feat: trace delegated routing http client #11017
  • fix(tracing): use context to pass trace and retrieval state to session boxo#1059
  • understand if this is a bug or feature: https://github.com/ipfs/boxo/pull/1059/files#r2466543123
    • fix: bitswap/client: propagate trace state when calling GetBlocks boxo#1060

• new webui chore: update webui to v4.10.0 #11048

  • new translations and feat(diagnostics/logs): include extended details ipfs-webui#2457
  • feat(diagnostics/logs): include extended details ipfs-webui#2457

• fix(gateway): deduplicate peer IDs in retrieval diagnostics boxo#1058

• fix for go-libp2p v0.44 logs not present in ipfs log tail #11035

  • go-libp2p release Release v0.45.0 libp2p/go-libp2p#3424
    • with fix from fix(websocket): use debug level for operational noise errors libp2p/go-libp2p#3413
    • with BREAKING CHANGE note for 0.44 and 0.45 release notes listing one-liner from Release v0.45.0 libp2p/go-libp2p#3424 (review)

• go-libp2p with fix(webrtc): use debug level for pion errors libp2p/go-libp2p#3426

Cherry-Pick for FINAL

• fix: inlude symlinks in scanning for init scripts #11077 (Docker)
• Update deprecation message for Reprovider fields [skip changelog] #11072 (typo)
• feat: support GetClosesPeers (IPIP-476) and ExposeRoutingAPI by default #10954 (pushed to 0.40 179e1f8)
• upgrade go-libp2p-kad-dht to v0.36.0 #11079

Nice To Have (Optional)

• Rewrite batch mode to use temp directory go-ds-flatfs#136
• Move ipfs routing provide and reprovide into ipfs provide namespace #10865 (keep old cmds as deprecated)
• panic: pebble: batch already committing #11014
• bug: failed to establish port mapping: goupnp: error performing SOAP HTTP request after LAN (upnp) router restart #9759
  • needs go-libp2p release with fix: self-healing NAT mappings with request deduplication libp2p/go-libp2p#3367 (without this, many Kubo-based providers fail as providers due to losing public addr)
• boxo with fix for denylist: ?format=car does not skip directly blocked CIDs #10361
  • fix(gateway): prevent blocked CIDs in CAR responses #10948
• feat(config): optional Gateway.MaxRangeRequestFileSize #10997
• Add CLI timeout for retrieval/resolution #10953
  • Kubo doesn't throw a proper error if I add content to the network with offline/inaccessible http routers #10952
• ipfs routing get should allow querying when node is offline by enabling a flag #10958
• quic-go with fix: return stream frames to pool on error paths quic-go/quic-go#5327
• ipfs repo copy: a way to move everything to different repo (config, pins, mfs, all blocks) #10938
• ipfs update: add built-in command, sunset ipfs-update #10937
• chore: golangci/v2 with go 1.25 support #10924
• deprecate go-ipfs docker image #10941
• feat(mfs): chroot command to change the root #8648
• feat(mfs): chroot command to change the root #8648 as fix for Ipfs daemon hangs when MFS root is not available locally #7183 (comment)
• Denylist support fixes and improvements
  • ipfs blockservice is incompatible with sessions ipfs-shipyard/nopfs#34 (NOfs content filtering is not applied to bitswap)
  • Support consuming https://badbits.dwebops.pub/badbits.deny rainbow#126 (same applies to Kubo)
    • denylist: ?format=car does not skip directly blocked CIDs #10361
    • HTTPSubscriber: detect when list is not append-only ipfs-shipyard/nopfs#39
    • HTTPSubscriber: check with If-None-Match or If-Modified-Since ipfs-shipyard/nopfs#38
• Update pubsub and add default validator #9684
• refactor: support percent-encoded /unix paths #10833
• Windows: redirect to *.ipfs.localhost fails in non-browser contexts #11024 (boxo with fix for gateway: UX improvement: browser-only subdomain redirects boxo#1054)
  • decision on Gologshim runtime controlled handler libp2p/go-libp2p#3419 (review)
  • fix(go-log@2.9/go-libp2p@0.45): dynamic log level control and tail #11039
• provider: duplicated CIDs sent to provide queue boxo#901 TBD

[lidel]

All "Required" items landed in master. I'm going to cut RC1 and start staging tests.
If no issues we may cut final one on Thursday or next week (if we need RC2).

[lidel]

✅ Release Checklist (v0.39.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: 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)

[lidel]

Early testers ping for Kubo 0.39.0 RC1 testing:

• Charity Engine (@Rytiss, @tristanolive)
• Fission (@bmann)
• Infura (@MichaelMure)
• OrbitDB (@haydenyoung)
• Pinata (@obo20)
• Shipyard (@cewood, @ns4plabs)
• Siderus (@koalalorenzo)
• Textile (@sanderpick)
• @RubenKelevra

You're getting this message because you're listed here. Please update this list if you no longer want to be included.

[Rashkae2]

Absolutely amazing work over the past 2 releases with regards to DHT. My test case is relatively tiny, (with only 150k CID's). but the first time starting 0.39-rc1, it re-published them all in initial burst, and finished the whole lot in under the 12 minutes Accelerated dht would take to bootstrap; with no noticeable impact to my internet connections. (and of course maintaining the sweeps afterwards completely painless.) My internet connection is residential 100/30mbps.

[lidel]

✅ Release Checklist (v0.39.0)

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