docs: Gateway.Writable deprecation plan

cmd/ipfs/daemon.go

@@ -162,7 +162,7 @@ Headers.
 		cmds.StringOption(initProfileOptionKwd, "Configuration profiles to apply for --init. See ipfs init --help for more"),
 		cmds.StringOption(routingOptionKwd, "Overrides the routing option").WithDefault(routingOptionDefaultKwd),
 		cmds.BoolOption(mountKwd, "Mounts IPFS to the filesystem using FUSE (experimental)"),
-		cmds.BoolOption(writableKwd, "Enable writing objects (with POST, PUT and DELETE, DEPRECATED)"),
+		cmds.BoolOption(writableKwd, "Enable legacy Gateway.Writable (deprecated)"),
 		cmds.StringOption(ipfsMountKwd, "Path to the mountpoint for IPFS (if using --mount). Defaults to config setting."),
 		cmds.StringOption(ipnsMountKwd, "Path to the mountpoint for IPNS (if using --mount). Defaults to config setting."),
 		cmds.BoolOption(unrestrictedAPIAccessKwd, "Allow API access to unlisted hashes"),
@@ -795,7 +795,7 @@ func serveHTTPGateway(req *cmds.Request, cctx *oldcmds.Context) (<-chan error, e
 	}
 
 	if writable {
-		log.Error("serveHTTPGateway: writable gateways are DEPRECATED and will be removed in future versions")
+		log.Error("serveHTTPGateway: legacy Gateway.Writable is DEPRECATED and will be removed or changed in future versions. If you are still using this, provide feedback in https://github.com/ipfs/specs/issues/375")
 	}
 
 	listeners, err := sockets.TakeListeners("io.ipfs.gateway")

config/gateway.go

@@ -38,8 +38,8 @@ type Gateway struct {
 	// should be redirected.
 	RootRedirect string
 
-	// DEPRECATED: Writable enables PUT/POST request handling by this gateway.
-	// Usually, writing is done through the API, not the gateway.
+	// DEPRECATED: Enables legacy PUT/POST request handling.
+	// Modern replacement tracked in https://github.com/ipfs/specs/issues/375
 	Writable Flag `json:",omitempty"`
 
 	// PathPrefixes was removed: https://github.com/ipfs/go-ipfs/issues/7702

docs/config.md

@@ -682,7 +682,10 @@ Type: `string` (url)
 
 ### `Gateway.Writable`
 
-**DEPRECATED**: A boolean to configure whether the gateway is writeable or not.
+**DEPRECATED**: Enables legacy PUT/POST request handling. 
+
+This API is not standardized, and should not be used for new projects.
+We are working on a modern replacement. IPIP can be tracked in [ipfs/specs#375](https://github.com/ipfs/specs/issues/375).
 
 Default: `false`