docs: restructure v0.39 changelog for clarity
- rewrite overview to lead with user value (self-hosting on consumer hardware) - reorder highlights: provider features together, then UPnP, then housekeeping - simplify titles (drop "Amino", "Fixed", verbose descriptions) - link to Shipyard's sweep provider blogpost
Marcin Rataj committed
Nov 26, 2025 at 21:52 UTC
40ffd166eab6877ad997544bac38084da2b9d2e5
2 files changed
+44
-38
docs/changelogs/v0.39.md
+43
-38
@@ -8,29 +8,33 @@ This release was brought to you by the [Shipyard](https://ipshipyard.com/) team.
8
9
## v0.39.0
10
11
+[<img align="right" width="256px" src="https://github.com/user-attachments/assets/427702e8-b6b8-4ac2-8425-18069626c321" />](https://github.com/user-attachments/assets/427702e8-b6b8-4ac2-8425-18069626c321)
12
+
13
- [Overview](#overview)
14
- [🔦 Highlights](#-highlights)
13
- - [🎯 Amino DHT Sweep provider is now the default](#-amino-dht-sweep-provider-is-now-the-default)
15
+ - [🎯 DHT Sweep provider is now the default](#-dht-sweep-provider-is-now-the-default)
16
- [⚡ Fast root CID providing for immediate content discovery](#-fast-root-cid-providing-for-immediate-content-discovery)
15
- - [📊 Detailed statistics for Sweep provider with `ipfs provide stat`](#-detailed-statistics-for-sweep-provider-with-ipfs-provide-stat)
16
- - [⏯️ Provider resume cycle for improved reproviding reliability](#provider-resume-cycle-for-improved-reproviding-reliability)
17
- - [🔔 Sweep provider slow reprovide warnings](#-sweep-provider-slow-reprovide-warnings)
17
+ - [⏯️ Provider state persists across restarts](#️-provider-state-persists-across-restarts)
18
+ - [📊 Detailed statistics with `ipfs provide stat`](#-detailed-statistics-with-ipfs-provide-stat)
19
+ - [🔔 Slow reprovide warnings](#-slow-reprovide-warnings)
20
- [📊 Metric rename: `provider_provides_total`](#-metric-rename-provider_provides_total)
19
- - [🔧 Fixed UPnP port forwarding after router restarts](#-fixed-upnp-port-forwarding-after-router-restarts)
20
- - [🖥️ RISC-V support with prebuilt binaries](#️-risc-v-support-with-prebuilt-binaries)
21
- - [🚦 Gateway range request limits for CDN compatibility](#-gateway-range-request-limits-for-cdn-compatibility)
21
+ - [🔧 Automatic UPnP recovery after router restarts](#-automatic-upnp-recovery-after-router-restarts)
22
- [🪦 Deprecated `go-ipfs` name no longer published](#-deprecated-go-ipfs-name-no-longer-published)
23
+ - [🚦 Gateway range request limits for CDN compatibility](#-gateway-range-request-limits-for-cdn-compatibility)
24
+ - [🖥️ RISC-V support with prebuilt binaries](#️-risc-v-support-with-prebuilt-binaries)
25
- [📦️ Important dependency updates](#-important-dependency-updates)
26
- [📝 Changelog](#-changelog)
27
- [👨👩👧👦 Contributors](#-contributors)
28
29
### Overview
30
29
-Kubo 0.39.0 graduates the experimental sweep provider to default, bringing efficient content announcement to all nodes. This release adds fast root CID providing for immediate content discovery via `ipfs add`, detailed provider statistics, automatic state persistence for reliable reproviding after restarts, and proactive monitoring alerts for identifying issues early. It also includes important fixes for UPnP port forwarding, RISC-V prebuilt binaries, and finalizes the deprecation of the legacy go-ipfs name.
31
+Kubo 0.39 makes self-hosting practical on consumer hardware and home networks. The DHT sweep provider (now default) announces your content to the network without traffic spikes that overwhelm residential connections. Automatic UPnP recovery means your node stays reachable after router restarts without manual intervention.
32
+
33
+New content becomes findable immediately after `ipfs add`. The provider system persists state across restarts, alerts you when falling behind, and exposes detailed stats for monitoring. This release also finalizes the deprecation of the legacy `go-ipfs` name.
34
35
### 🔦 Highlights
36
33
-#### 🎯 Amino DHT Sweep provider is now the default
37
+#### 🎯 DHT Sweep provider is now the default
38
39
The Amino DHT Sweep provider system, introduced as experimental in v0.38, is now enabled by default (`Provide.DHT.SweepEnabled=true`).
40
@@ -41,16 +45,17 @@ The Amino DHT Sweep provider system, introduced as experimental in v0.38, is now
45
- If you explicitly set `Provide.DHT.SweepEnabled=false` in v0.38, you'll continue using the legacy provider
46
- If you were using the default settings, you'll automatically get the sweep provider
47
- To opt out and return to legacy behavior: `ipfs config --json Provide.DHT.SweepEnabled false`
48
+- Providers with medium to large datasets may need to adjust defaults; see [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning)
49
50
**New features available with sweep mode:**
51
47
-- Detailed statistics via `ipfs provide stat` ([see below](#-detailed-statistics-for-sweep-provider-with-ipfs-provide-stat))
48
-- Automatic resume after restarts with persistent state ([see below](#provider-resume-cycle-for-improved-reproviding-reliability))
49
-- Proactive alerts when reproviding falls behind ([see below](#-sweep-provider-slow-reprovide-warnings))
52
+- Detailed statistics via `ipfs provide stat` ([see below](#-detailed-statistics-with-ipfs-provide-stat))
53
+- Automatic resume after restarts with persistent state ([see below](#️-provider-state-persists-across-restarts))
54
+- Proactive alerts when reproviding falls behind ([see below](#-slow-reprovide-warnings))
55
- Better metrics for monitoring (`provider_provides_total`) ([see below](#-metric-rename-provider_provides_total))
56
- Fast optimistic provide of new root CIDs ([see below](#-fast-root-cid-providing-for-immediate-content-discovery))
57
53
-For background on the sweep provider design and motivations, see [`Provide.DHT.SweepEnabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtsweepenabled) and [ipshipyard.com#8](https://github.com/ipshipyard/ipshipyard.com/pull/8).
58
+For background on the sweep provider design and motivations, see [`Provide.DHT.SweepEnabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtsweepenabled) and Shipyard's blogpost [Provide Sweep: Solving the DHT Provide Bottleneck](https://ipshipyard.com/blog/2025-dht-provide-sweep/).
59
60
#### ⚡ Fast root CID providing for immediate content discovery
61
@@ -74,7 +79,18 @@ ipfs dag import file.car # Same for CAR imports
79
80
This optimization works best with the sweep provider and accelerated DHT client, where provide operations are significantly faster. Automatically skipped when DHT is unavailable (e.g., `Routing.Type=none` or delegated-only configurations).
81
77
-#### 📊 Detailed statistics for Sweep provider with `ipfs provide stat`
82
+#### ⏯️ Provider state persists across restarts
83
+
84
+The Sweep provider now persists the reprovide cycle state and automatically resumes where it left off after a restart. This brings several improvements:
85
+
86
+- **Persistent progress**: The provider saves its position in the reprovide cycle to the datastore. On restart, it continues from where it stopped instead of starting from scratch.
87
+- **Catch-up reproviding**: If the node was offline for an extended period, all CIDs that haven't been reprovided within the configured reprovide interval are immediately queued for reproviding when the node starts up. This ensures content availability is maintained even after downtime.
88
+- **Persistent provide queue**: The provide queue is persisted to the datastore on shutdown. When the node restarts, queued CIDs are restored and provided as expected, preventing loss of pending provide operations.
89
+- **Resume control**: The resume behavior is controlled via [`Provide.DHT.ResumeEnabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtresumeenabled) (default: `true`). Set to `false` if you don't want to keep the persisted provider state from a previous run.
90
+
91
+This feature improves reliability for nodes that experience intermittent connectivity or restarts.
92
+
93
+#### 📊 Detailed statistics with `ipfs provide stat`
94
95
The Sweep provider system now exposes detailed statistics through `ipfs provide stat`, helping you monitor provider health and troubleshoot issues.
96
@@ -82,23 +98,12 @@ Run `ipfs provide stat` for a quick summary, or use `--all` to see complete metr
98
99
For Dual DHT configurations, use `--lan` to view LAN DHT statistics instead of the default WAN DHT stats.
100
85
-For more information, run `ipfs provide stat --help` or see the [Provide Stats documentation](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md).
101
+For more information, run `ipfs provide stat --help` or see the [Provide Stats documentation](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md), including [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning).
102
103
> [!NOTE]
104
> Legacy provider (when `Provide.DHT.SweepEnabled=false`) shows basic statistics without flag support.
105
90
-#### ⏯️ Provider resume cycle for improved reproviding reliability
91
-
92
-The Sweep provider now persists the reprovide cycle state and automatically resumes where it left off after a restart. This brings several improvements:
93
-
94
-- **Persistent progress**: The provider saves its position in the reprovide cycle to the datastore. On restart, it continues from where it stopped instead of starting from scratch.
95
-- **Catch-up reproviding**: If the node was offline for an extended period, all CIDs that haven't been reprovided within the configured reprovide interval are immediately queued for reproviding when the node starts up. This ensures content availability is maintained even after downtime.
96
-- **Persistent provide queue**: The provide queue is persisted to the datastore on shutdown. When the node restarts, queued CIDs are restored and provided as expected, preventing loss of pending provide operations.
97
-- **Resume control**: The resume behavior is controlled via [`Provide.DHT.ResumeEnabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#providedhtresumeenabled) (default: `true`). Set to `false` if you don't want to keep the persisted provider state from a previous run.
98
-
99
-This feature improves reliability for nodes that experience intermittent connectivity or restarts.
100
-
101
-#### 🔔 Sweep provider slow reprovide warnings
106
+#### 🔔 Slow reprovide warnings
107
108
Kubo now monitors DHT reprovide operations when `Provide.DHT.SweepEnabled=true`
109
and alerts you if your node is falling behind on reprovides.
@@ -120,7 +125,7 @@ The Amino DHT Sweep provider metric has been renamed from `total_provide_count_t
125
126
**Migration:** If you have Prometheus queries, dashboards, or alerts monitoring the old `total_provide_count_total` metric, update them to use `provider_provides_total` instead. This affects all nodes using sweep mode, which is now the default in v0.39 (previously opt-in experimental in v0.38).
127
123
-#### 🔧 Fixed UPnP port forwarding after router restarts
128
+#### 🔧 Automatic UPnP recovery after router restarts
129
130
Kubo now automatically recovers UPnP port mappings when routers restart or
131
become temporarily unavailable, fixing a critical connectivity issue that
@@ -144,13 +149,15 @@ without manual intervention.
149
This significantly improves reliability for desktop and self-hosted IPFS nodes
150
using UPnP for NAT traversal.
151
147
-#### 🖥️ RISC-V support with prebuilt binaries
152
+#### 🪦 Deprecated `go-ipfs` name no longer published
153
149
-Kubo provides official `linux-riscv64` prebuilt binaries, bringing IPFS to [RISC-V](https://en.wikipedia.org/wiki/RISC-V) open hardware.
154
+The `go-ipfs` name was deprecated in 2022 and renamed to `kubo`. Starting with this release, the legacy Docker image name has been replaced with a stub that displays an error message directing users to switch to `ipfs/kubo`.
155
151
-As RISC-V single-board computers and embedded systems become more accessible, the distributed web is now supported on open hardware architectures - a natural pairing of open technologies.
156
+**Docker images:** The `ipfs/go-ipfs` image tags now contain only a stub script that exits with an error, instructing users to update their Docker configurations to use [`ipfs/kubo`](https://hub.docker.com/r/ipfs/kubo) instead. This ensures users are aware of the deprecation while allowing existing automation to fail explicitly rather than silently using outdated images.
157
153
-Download from <https://dist.ipfs.tech/kubo/> or <https://github.com/ipfs/kubo/releases> and look for the `linux-riscv64` archive.
158
+**Distribution binaries:** Download Kubo from <https://dist.ipfs.tech/kubo/> or <https://github.com/ipfs/kubo/releases>. The legacy `go-ipfs` distribution path should no longer be used.
159
+
160
+All users should migrate to the `kubo` name in their scripts and configurations.
161
162
#### 🚦 Gateway range request limits for CDN compatibility
163
@@ -158,15 +165,13 @@ The new [`Gateway.MaxRangeRequestFileSize`](https://github.com/ipfs/kubo/blob/ma
165
166
This only impacts deserialized responses. Clients using verifiable block requests (`application/vnd.ipld.raw`) are not affected. See the [configuration documentation](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaymaxrangerequestfilesize) for details.
167
161
-#### 🪦 Deprecated `go-ipfs` name no longer published
162
-
163
-The `go-ipfs` name was deprecated in 2022 and renamed to `kubo`. Starting with this release, the legacy Docker image name has been replaced with a stub that displays an error message directing users to switch to `ipfs/kubo`.
168
+#### 🖥️ RISC-V support with prebuilt binaries
169
165
-**Docker images:** The `ipfs/go-ipfs` image tags now contain only a stub script that exits with an error, instructing users to update their Docker configurations to use [`ipfs/kubo`](https://hub.docker.com/r/ipfs/kubo) instead. This ensures users are aware of the deprecation while allowing existing automation to fail explicitly rather than silently using outdated images.
170
+Kubo provides official `linux-riscv64` prebuilt binaries, bringing IPFS to [RISC-V](https://en.wikipedia.org/wiki/RISC-V) open hardware.
171
167
-**Distribution binaries:** Download Kubo from <https://dist.ipfs.tech/kubo/> or <https://github.com/ipfs/kubo/releases>. The legacy `go-ipfs` distribution path should no longer be used.
172
+As RISC-V single-board computers and embedded systems become more accessible, the distributed web is now supported on open hardware architectures - a natural pairing of open technologies.
173
169
-All users should migrate to the `kubo` name in their scripts and configurations.
174
+Download from <https://dist.ipfs.tech/kubo/> or <https://github.com/ipfs/kubo/releases> and look for the `linux-riscv64` archive.
175
176
### 📦️ Important dependency updates
177
docs/config.md
+1
@@ -2118,6 +2118,7 @@ connections this setting can generate.
2118
> users. The system will only use workers as needed - unused resources won't be
2119
> consumed. Ensure you adjust the swarm [connection manager](#swarmconnmgr) and
2120
> [resource manager](#swarmresourcemgr) configuration accordingly.
2121
+> See [Capacity Planning](https://github.com/ipfs/kubo/blob/master/docs/provide-stats.md#capacity-planning) for more details.
2122
2123
Default: `16`
2124