docs(ipip-402): ipip and dag import changelog

docs/changelogs/v0.21.md

@@ -4,20 +4,19 @@
 
 ## v0.21.0
 
-* [v0.21.0](#v0210)
-  * [Overview](#overview)
-  * [🔦 Highlights](#-highlights)
-    * [Saving previously seen nodes for later bootstrapping](#saving-previously-seen-nodes-for-later-bootstrapping)
-    * [Gateway: `DeserializedResponses` config flag](#gateway-deserializedresponses-config-flag)
-    * [`client/rpc` migration of `go-ipfs-http-client`](#clientrpc-migration-of-go-ipfs-http-client)
-    * [Gateway: DAG-CBOR/-JSON previews and improved error pages](#gateway-dag-cbor-json-previews-and-improved-error-pages)
-    * [Gateway: subdomain redirects are now `text/html`](#gateway-subdomain-redirects-are-now-texthtml)
-    * [Gateway: support for CAR parameters of IPIP-402](#gateway-support-for-car-parameters-of-ipip-402)
-    * [`ipfs dag import` no longer pins by default](#ipfs-dag-import-no-longer-pins-by-default)
-    * [`ipfs dag stat` deduping statistics](#ipfs-dag-stat-deduping-statistics)
-    * [Accelerated DHT Client is no longer experimental](#accelerated-dht-client-is-no-longer-experimental)
-  * [📝 Changelog](#-changelog)
-  * [👨‍👩‍👧‍👦 Contributors](#-contributors)
+- [Overview](#overview)
+- [🔦 Highlights](#-highlights)
+  - [Saving previously seen nodes for later bootstrapping](#saving-previously-seen-nodes-for-later-bootstrapping)
+  - [Gateway: `DeserializedResponses` config flag](#gateway-deserializedresponses-config-flag)
+  - [`client/rpc` migration of `go-ipfs-http-client`](#clientrpc-migration-of-go-ipfs-http-client)
+  - [Gateway: DAG-CBOR/-JSON previews and improved error pages](#gateway-dag-cbor-json-previews-and-improved-error-pages)
+  - [Gateway: subdomain redirects are now `text/html`](#gateway-subdomain-redirects-are-now-texthtml)
+  - [Gateway: support for partial CAR export parameters (IPIP-402)](#gateway-support-for-partial-car-export-parameters-ipip-402)
+  - [`ipfs dag import` no longer pins by default](#ipfs-dag-import-no-longer-pins-by-default)
+  - [`ipfs dag stat` deduping statistics](#ipfs-dag-stat-deduping-statistics)
+  - [Accelerated DHT Client is no longer experimental](#accelerated-dht-client-is-no-longer-experimental)
+- [📝 Changelog](#-changelog)
+- [👨‍👩‍👧‍👦 Contributors](#-contributors)
 
 ### Overview
 
@@ -107,13 +106,36 @@ $ curl "https://subdomain-gw.example.net/ipfs/${cid}/"
 
 Rationale can be found in [kubo#9913](https://github.com/ipfs/kubo/pull/9913).
 
-#### Gateway: support for CAR parameters of IPIP-402
+#### Gateway: support for partial CAR export parameters (IPIP-402)
 
-The gateway now supports partial CAR export parameters as indicated in [IPIP-402](https://github.com/ipfs/specs/pull/402).
+The gateway now supports optional CAR export parameters
+`dag-scope=block|entity|all` and `entity-bytes=from:to` as specified in
+[IPIP-402](https://github.com/ipfs/specs/pull/402).
+
+Batch block retrieval minimizes round trips, catering to the requirements of
+light HTTP clients for directory enumeration, range requests, and content path
+resolution.
 
 #### `ipfs dag import` no longer pins by default
 
-With the gateway now supporting partial CAR exports, and incomplete DAG CARs becoming increasingly common. The pinning mode when using `ipfs dag import` has changed such that pinning the DAG or part of a DAG within an imported CAR is optional. To attempt to pin the DAG referenced by any roots in the CAR, opt in with the `--pin-roots` option.
+With the gateway now capable of handling partial CAR exports
+([IPIP-402](https://github.com/ipfs/specs/pull/402)) and incomplete DAG CARs
+becoming more prevalent, there have been changes to the pinning mode when using
+`ipfs dag import`.
+
+Recursive pinning of the entire DAG within an imported CAR is now optional.  To
+explicitly attempt pinning the DAG referenced by any roots present in the CAR,
+you can opt in by using the `--pin-roots` option.
+
+Pinning incomplete DAG will produce an error:
+
+```console
+$ curl 'http://127.0.0.1:8080/ipns/docs.ipfs.tech?format=car&dag-scope=entity' > ./partial-entity.car # Kubo 0.21.0 with IPIP-402 (only root block of unixfs dir)
+$ ipfs dag import --stats --pin-roots=true ./partial-entity.car
+Error pinning	QmPDC11yLAbVw3dX5jMeEuSdk4BiVjSd9X87zaYRdVjzW3	FAILED: block was not found locally (offline): ipld: could not find QmPDvrDAz2aHeLjPVQ4uh1neyknUmDpf1GsBzAbpFhS8ro
+Imported 1 blocks (1618 bytes)
+[exit code 1]
+```
 
 #### `ipfs dag stat` deduping statistics