From a61c53f87fc6b5341c8d0a0b088cb16dd59f8cc8 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 22 Mar 2022 20:46:32 +0100 Subject: [PATCH] feat(cmds): document deprecated RPC API commands (#8802) * feat(cmds): add deprecated and experimental status Added programmatic state annotation introduced in https://github.com/ipfs/go-ipfs-cmds/pull/225 for already deprecated / experimental commands. * chore: go-ipfs-cmds v0.7.0 Co-authored-by: Lucas Molas --- core/commands/dag/dag.go | 6 +++--- core/commands/name/ipnsps.go | 4 ++++ core/commands/object/diff.go | 1 + core/commands/object/object.go | 7 +++++++ core/commands/object/patch.go | 5 +++++ core/commands/p2p.go | 8 ++++++++ core/commands/pubsub.go | 5 +++++ core/commands/repo.go | 1 + core/commands/unixfs/ls.go | 3 ++- core/commands/unixfs/unixfs.go | 11 +++-------- core/commands/urlstore.go | 1 + go.mod | 2 +- go.sum | 4 ++-- 13 files changed, 43 insertions(+), 15 deletions(-) diff --git a/core/commands/dag/dag.go b/core/commands/dag/dag.go index 6d2e480b284..d5d7479f268 100644 --- 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 index 31791570970..949ea43d5e8 100644 --- 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 index d83da7cec5d..54727cd287f 100644 --- 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 index 1e145208a59..00f2f44ce3d 100644 --- 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 index ab76ebb23f4..6843b226765 100644 --- 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 index 77e7ca2b4f8..e9c32626bc4 100644 --- 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 index 47d893852af..570f850d097 100644 --- 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 index c4066f50e56..367a6d901da 100644 --- 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 index e5fd4e0c260..ac012b04fe4 100644 --- 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 index f1dfabc91e0..cb5c8ddaf32 100644 --- 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 index c71229b5a6e..0b7dcbc5f50 100644 --- 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 index 9e290f9a12f..1fd95dee40d 100644 --- 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 index 71490b133d1..43f65b68404 100644 --- 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=