feat(cmds): document deprecated RPC API commands (#8802)

* feat(cmds): add deprecated and experimental status Added programmatic state annotation introduced in ipfs/go-ipfs-cmds#225 for already deprecated / experimental commands. * chore: go-ipfs-cmds v0.7.0 Co-authored-by: Lucas Molas <schomatis@gmail.com>
ipfs · Mar 22, 2022 · a61c53f · a61c53f
1 parent c854390
commit a61c53f
Show file tree

Hide file tree

Showing 13 changed files with 43 additions and 15 deletions.
diff --git a/core/commands/dag/dag.go b/core/commands/dag/dag.go
@@ -30,9 +30,9 @@ var DagCmd = &cmds.Command{
 		ShortDescription: `
 'ipfs dag' is used for creating and manipulating DAG objects/hierarchies.
 
-This subcommand is currently an experimental feature, but it is intended
-to deprecate and replace the existing 'ipfs object' command moving forward.
-		`,
+This subcommand is intended to deprecate and replace
+the existing 'ipfs object' command moving forward.
+`,
 	},
 	Subcommands: map[string]*cmds.Command{
 		"put":     DagPutCmd,

diff --git a/core/commands/name/ipnsps.go b/core/commands/name/ipnsps.go
@@ -26,6 +26,7 @@ type stringList struct {
 
 // IpnsPubsubCmd is the subcommand that allows us to manage the IPNS pubsub system
 var IpnsPubsubCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "IPNS pubsub management",
 		ShortDescription: `
@@ -42,6 +43,7 @@ Note: this command is experimental and subject to change as the system is refine
 }
 
 var ipnspsStateCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Query the state of IPNS pubsub.",
 	},
@@ -70,6 +72,7 @@ var ipnspsStateCmd = &cmds.Command{
 }
 
 var ipnspsSubsCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Show current name subscriptions.",
 	},
@@ -114,6 +117,7 @@ var ipnspsSubsCmd = &cmds.Command{
 }
 
 var ipnspsCancelCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Cancel a name subscription.",
 	},

diff --git a/core/commands/object/diff.go b/core/commands/object/diff.go
@@ -20,6 +20,7 @@ type Changes struct {
 }
 
 var ObjectDiffCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Display the diff between two IPFS objects.",
 		ShortDescription: `

diff --git a/core/commands/object/object.go b/core/commands/object/object.go
@@ -47,6 +47,7 @@ const (
 )
 
 var ObjectCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated commands to interact with dag-pb objects. Use 'dag' or 'files' instead.",
 		ShortDescription: `
@@ -68,6 +69,7 @@ directly. Deprecated, use more modern 'ipfs dag' and 'ipfs files' instead.`,
 
 // ObjectDataCmd object data command
 var ObjectDataCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to read the raw bytes of a dag-pb object: use 'dag get' instead.",
 		ShortDescription: `
@@ -107,6 +109,7 @@ is the raw data of the object.
 
 // ObjectLinksCmd object links command
 var ObjectLinksCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to output links in the specified dag-pb object: use 'dag get' instead.",
 		ShortDescription: `
@@ -181,6 +184,7 @@ multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
 
 // ObjectGetCmd object get command
 var ObjectGetCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to get and serialize the dag-pb node. Use 'dag get' instead",
 		ShortDescription: `
@@ -272,6 +276,7 @@ DEPRECATED and provided for legacy reasons. Use 'ipfs dag get' instead.
 
 // ObjectStatCmd object stat command
 var ObjectStatCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to read stats for the dag-pb node. Use 'files stat' instead.",
 		ShortDescription: `
@@ -371,6 +376,7 @@ DEPRECATED: Provided for legacy reasons. Modern replacements:
 
 // ObjectPutCmd object put command
 var ObjectPutCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to store input as a DAG object. Use 'dag put' instead.",
 		ShortDescription: `
@@ -450,6 +456,7 @@ DEPRECATED and provided for legacy reasons. Use 'ipfs dag put' instead.
 
 // ObjectNewCmd object new command
 var ObjectNewCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to create a new dag-pb object from a template.",
 		ShortDescription: `

diff --git a/core/commands/object/patch.go b/core/commands/object/patch.go
@@ -13,6 +13,7 @@ import (
 )
 
 var ObjectPatchCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to create a new merkledag object based on an existing one. Use MFS with 'files cp|rm' instead.",
 		ShortDescription: `
@@ -48,6 +49,7 @@ For modern use cases, use MFS with 'files' commands: 'ipfs files --help'.
 }
 
 var patchAppendDataCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to append data to the data segment of a DAG node.",
 		ShortDescription: `
@@ -102,6 +104,7 @@ DEPRECATED and provided for legacy reasons. Use 'ipfs add' or 'ipfs files' inste
 }
 
 var patchSetDataCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to set the data field of dag-pb object.",
 		ShortDescription: `
@@ -152,6 +155,7 @@ DEPRECATED and provided for legacy reasons. Use 'files cp' and 'dag put' instead
 }
 
 var patchRmLinkCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to remove a link from dag-pb object.",
 		ShortDescription: `
@@ -198,6 +202,7 @@ const (
 )
 
 var patchAddLinkCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
 	Helptext: cmds.HelpText{
 		Tagline: "Deprecated way to add a link to a given dag-pb.",
 		ShortDescription: `

diff --git a/core/commands/p2p.go b/core/commands/p2p.go
@@ -59,6 +59,7 @@ var resolveTimeout = 10 * time.Second
 
 // P2PCmd is the 'ipfs p2p' command
 var P2PCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Libp2p stream mounting.",
 		ShortDescription: `
@@ -78,6 +79,7 @@ are refined`,
 }
 
 var p2pForwardCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Forward connections to libp2p service.",
 		ShortDescription: `
@@ -179,6 +181,7 @@ func parseIpfsAddr(addr string) (*peer.AddrInfo, error) {
 }
 
 var p2pListenCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Create libp2p service.",
 		ShortDescription: `
@@ -280,6 +283,7 @@ const (
 )
 
 var p2pLsCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "List active p2p listeners.",
 	},
@@ -343,6 +347,7 @@ const (
 )
 
 var p2pCloseCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Stop listening for new connections to forward.",
 	},
@@ -427,6 +432,7 @@ var p2pCloseCmd = &cmds.Command{
 
 // p2pStreamCmd is the 'ipfs p2p stream' command
 var p2pStreamCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline:          "P2P stream management.",
 		ShortDescription: "Create and manage p2p streams",
@@ -439,6 +445,7 @@ var p2pStreamCmd = &cmds.Command{
 }
 
 var p2pStreamLsCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "List active p2p streams.",
 	},
@@ -488,6 +495,7 @@ var p2pStreamLsCmd = &cmds.Command{
 }
 
 var p2pStreamCloseCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Close active p2p stream.",
 	},

diff --git a/core/commands/pubsub.go b/core/commands/pubsub.go
@@ -17,6 +17,7 @@ import (
 )
 
 var PubsubCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "An experimental publish-subscribe system on ipfs.",
 		ShortDescription: `
@@ -46,6 +47,7 @@ type pubsubMessage struct {
 }
 
 var PubsubSubCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Subscribe to messages on a given topic.",
 		ShortDescription: `
@@ -144,6 +146,7 @@ TOPIC AND DATA ENCODING
 }
 
 var PubsubPubCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Publish data to a given pubsub topic.",
 		ShortDescription: `
@@ -199,6 +202,7 @@ HTTP RPC ENCODING
 }
 
 var PubsubLsCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "List subscribed topics by name.",
 		ShortDescription: `
@@ -270,6 +274,7 @@ func safeTextListEncoder(req *cmds.Request, w io.Writer, list *stringList) error
 }
 
 var PubsubPeersCmd = &cmds.Command{
+	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "List peers we are currently pubsubbing with.",
 		ShortDescription: `

diff --git a/core/commands/repo.go b/core/commands/repo.go
@@ -222,6 +222,7 @@ Version         string The repo version.
 }
 
 var repoFsckCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/6435
 	Helptext: cmds.HelpText{
 		Tagline: "Remove repo lockfiles.",
 		ShortDescription: `

diff --git a/core/commands/unixfs/ls.go b/core/commands/unixfs/ls.go
@@ -33,8 +33,9 @@ type LsOutput struct {
 }
 
 var LsCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/pull/7755
 	Helptext: cmds.HelpText{
-		Tagline: "List directory contents for Unix filesystem objects. Deprecated: Use 'ipfs ls' instead.",
+		Tagline: "List directory contents for Unix filesystem objects. Deprecated: Use 'ipfs ls' and 'ipfs files ls' instead.",
 		ShortDescription: `
 Displays the contents of an IPFS or IPNS object(s) at the given path.
 

diff --git a/core/commands/unixfs/unixfs.go b/core/commands/unixfs/unixfs.go
@@ -5,17 +5,12 @@ import (
 )
 
 var UnixFSCmd = &cmds.Command{
+	Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/pull/7755
 	Helptext: cmds.HelpText{
 		Tagline: "Interact with IPFS objects representing Unix filesystems.",
 		ShortDescription: `
-'ipfs file' provides a familiar interface to file systems represented
-by IPFS objects, which hides ipfs implementation details like layout
-objects (e.g. fanout and chunking).
-`,
-		LongDescription: `
-'ipfs file' provides a familiar interface to file systems represented
-by IPFS objects, which hides ipfs implementation details like layout
-objects (e.g. fanout and chunking).
+Old interface to file systems represented by UnixFS.
+Superseded by modern alternatives: 'ipfs ls' and 'ipfs files'
 `,
 	},
 

diff --git a/core/commands/urlstore.go b/core/commands/urlstore.go
@@ -23,6 +23,7 @@ var urlStoreCmd = &cmds.Command{
 }
 
 var urlAdd = &cmds.Command{
+	Status: cmds.Deprecated,
 	Helptext: cmds.HelpText{
 		Tagline: "Add URL via urlstore.",
 		LongDescription: `

diff --git a/go.mod b/go.mod
@@ -31,7 +31,7 @@ require (
 	github.com/ipfs/go-graphsync v0.11.0
 	github.com/ipfs/go-ipfs-blockstore v1.2.0
 	github.com/ipfs/go-ipfs-chunker v0.0.5
-	github.com/ipfs/go-ipfs-cmds v0.6.0
+	github.com/ipfs/go-ipfs-cmds v0.7.0
 	github.com/ipfs/go-ipfs-exchange-interface v0.1.0
 	github.com/ipfs/go-ipfs-exchange-offline v0.2.0
 	github.com/ipfs/go-ipfs-files v0.0.9

diff --git a/go.sum b/go.sum
@@ -473,8 +473,8 @@ github.com/ipfs/go-ipfs-blocksutil v0.0.1/go.mod h1:Yq4M86uIOmxmGPUHv/uI7uKqZNtL
 github.com/ipfs/go-ipfs-chunker v0.0.1/go.mod h1:tWewYK0we3+rMbOh7pPFGDyypCtvGcBFymgY4rSDLAw=
 github.com/ipfs/go-ipfs-chunker v0.0.5 h1:ojCf7HV/m+uS2vhUGWcogIIxiO5ubl5O57Q7NapWLY8=
 github.com/ipfs/go-ipfs-chunker v0.0.5/go.mod h1:jhgdF8vxRHycr00k13FM8Y0E+6BoalYeobXmUyTreP8=
-github.com/ipfs/go-ipfs-cmds v0.6.0 h1:yAxdowQZzoFKjcLI08sXVNnqVj3jnABbf9smrPQmBsw=
-github.com/ipfs/go-ipfs-cmds v0.6.0/go.mod h1:ZgYiWVnCk43ChwoH8hAmI1IRbuVtq3GSTHwtRB/Kqhk=
+github.com/ipfs/go-ipfs-cmds v0.7.0 h1:0lEldmB7C83RxIOer38Sv1ob6wIoCAIEOaxiYgcv7wA=
+github.com/ipfs/go-ipfs-cmds v0.7.0/go.mod h1:y0bflH6m4g6ary4HniYt98UqbrVnRxmRarzeMdLIUn0=
 github.com/ipfs/go-ipfs-delay v0.0.0-20181109222059-70721b86a9a8/go.mod h1:8SP1YXK1M1kXuc4KJZINY3TQQ03J2rwBG9QfXmbRPrw=
 github.com/ipfs/go-ipfs-delay v0.0.1 h1:r/UXYyRcddO6thwOnhiznIAiSvxMECGgtv35Xs1IeRQ=
 github.com/ipfs/go-ipfs-delay v0.0.1/go.mod h1:8SP1YXK1M1kXuc4KJZINY3TQQ03J2rwBG9QfXmbRPrw=