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 <schomatis@gmail.com>
Marcin Rataj committed
Mar 22, 2022 at 20:46 UTC
a61c53f87fc6b5341c8d0a0b088cb16dd59f8cc8
13 files changed
+43
-15
core/commands/dag/dag.go
+3
-3
@@ -30,9 +30,9 @@ var DagCmd = &cmds.Command{
30
ShortDescription: `
31
'ipfs dag' is used for creating and manipulating DAG objects/hierarchies.
32
33
-This subcommand is currently an experimental feature, but it is intended
34
-to deprecate and replace the existing 'ipfs object' command moving forward.
35
- `,
33
+This subcommand is intended to deprecate and replace
34
+the existing 'ipfs object' command moving forward.
35
+`,
36
},
37
Subcommands: map[string]*cmds.Command{
38
"put": DagPutCmd,
core/commands/name/ipnsps.go
+4
@@ -26,6 +26,7 @@ type stringList struct {
26
27
// IpnsPubsubCmd is the subcommand that allows us to manage the IPNS pubsub system
28
var IpnsPubsubCmd = &cmds.Command{
29
+ Status: cmds.Experimental,
30
Helptext: cmds.HelpText{
31
Tagline: "IPNS pubsub management",
32
ShortDescription: `
@@ -42,6 +43,7 @@ Note: this command is experimental and subject to change as the system is refine
43
}
44
45
var ipnspsStateCmd = &cmds.Command{
46
+ Status: cmds.Experimental,
47
Helptext: cmds.HelpText{
48
Tagline: "Query the state of IPNS pubsub.",
49
},
@@ -70,6 +72,7 @@ var ipnspsStateCmd = &cmds.Command{
72
}
73
74
var ipnspsSubsCmd = &cmds.Command{
75
+ Status: cmds.Experimental,
76
Helptext: cmds.HelpText{
77
Tagline: "Show current name subscriptions.",
78
},
@@ -114,6 +117,7 @@ var ipnspsSubsCmd = &cmds.Command{
117
}
118
119
var ipnspsCancelCmd = &cmds.Command{
120
+ Status: cmds.Experimental,
121
Helptext: cmds.HelpText{
122
Tagline: "Cancel a name subscription.",
123
},
core/commands/object/diff.go
+1
@@ -20,6 +20,7 @@ type Changes struct {
20
}
21
22
var ObjectDiffCmd = &cmds.Command{
23
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
24
Helptext: cmds.HelpText{
25
Tagline: "Display the diff between two IPFS objects.",
26
ShortDescription: `
core/commands/object/object.go
+7
@@ -47,6 +47,7 @@ const (
47
)
48
49
var ObjectCmd = &cmds.Command{
50
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
51
Helptext: cmds.HelpText{
52
Tagline: "Deprecated commands to interact with dag-pb objects. Use 'dag' or 'files' instead.",
53
ShortDescription: `
@@ -68,6 +69,7 @@ directly. Deprecated, use more modern 'ipfs dag' and 'ipfs files' instead.`,
69
70
// ObjectDataCmd object data command
71
var ObjectDataCmd = &cmds.Command{
72
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
73
Helptext: cmds.HelpText{
74
Tagline: "Deprecated way to read the raw bytes of a dag-pb object: use 'dag get' instead.",
75
ShortDescription: `
@@ -107,6 +109,7 @@ is the raw data of the object.
109
110
// ObjectLinksCmd object links command
111
var ObjectLinksCmd = &cmds.Command{
112
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
113
Helptext: cmds.HelpText{
114
Tagline: "Deprecated way to output links in the specified dag-pb object: use 'dag get' instead.",
115
ShortDescription: `
@@ -181,6 +184,7 @@ multihash. Provided for legacy reasons. Use 'ipfs dag get' instead.
184
185
// ObjectGetCmd object get command
186
var ObjectGetCmd = &cmds.Command{
187
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
188
Helptext: cmds.HelpText{
189
Tagline: "Deprecated way to get and serialize the dag-pb node. Use 'dag get' instead",
190
ShortDescription: `
@@ -272,6 +276,7 @@ DEPRECATED and provided for legacy reasons. Use 'ipfs dag get' instead.
276
277
// ObjectStatCmd object stat command
278
var ObjectStatCmd = &cmds.Command{
279
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
280
Helptext: cmds.HelpText{
281
Tagline: "Deprecated way to read stats for the dag-pb node. Use 'files stat' instead.",
282
ShortDescription: `
@@ -371,6 +376,7 @@ DEPRECATED: Provided for legacy reasons. Modern replacements:
376
377
// ObjectPutCmd object put command
378
var ObjectPutCmd = &cmds.Command{
379
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
380
Helptext: cmds.HelpText{
381
Tagline: "Deprecated way to store input as a DAG object. Use 'dag put' instead.",
382
ShortDescription: `
@@ -450,6 +456,7 @@ DEPRECATED and provided for legacy reasons. Use 'ipfs dag put' instead.
456
457
// ObjectNewCmd object new command
458
var ObjectNewCmd = &cmds.Command{
459
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
460
Helptext: cmds.HelpText{
461
Tagline: "Deprecated way to create a new dag-pb object from a template.",
462
ShortDescription: `
core/commands/object/patch.go
+5
@@ -13,6 +13,7 @@ import (
13
)
14
15
var ObjectPatchCmd = &cmds.Command{
16
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
17
Helptext: cmds.HelpText{
18
Tagline: "Deprecated way to create a new merkledag object based on an existing one. Use MFS with 'files cp|rm' instead.",
19
ShortDescription: `
@@ -48,6 +49,7 @@ For modern use cases, use MFS with 'files' commands: 'ipfs files --help'.
49
}
50
51
var patchAppendDataCmd = &cmds.Command{
52
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
53
Helptext: cmds.HelpText{
54
Tagline: "Deprecated way to append data to the data segment of a DAG node.",
55
ShortDescription: `
@@ -102,6 +104,7 @@ DEPRECATED and provided for legacy reasons. Use 'ipfs add' or 'ipfs files' inste
104
}
105
106
var patchSetDataCmd = &cmds.Command{
107
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
108
Helptext: cmds.HelpText{
109
Tagline: "Deprecated way to set the data field of dag-pb object.",
110
ShortDescription: `
@@ -152,6 +155,7 @@ DEPRECATED and provided for legacy reasons. Use 'files cp' and 'dag put' instead
155
}
156
157
var patchRmLinkCmd = &cmds.Command{
158
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
159
Helptext: cmds.HelpText{
160
Tagline: "Deprecated way to remove a link from dag-pb object.",
161
ShortDescription: `
@@ -198,6 +202,7 @@ const (
202
)
203
204
var patchAddLinkCmd = &cmds.Command{
205
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/7936
206
Helptext: cmds.HelpText{
207
Tagline: "Deprecated way to add a link to a given dag-pb.",
208
ShortDescription: `
core/commands/p2p.go
+8
@@ -59,6 +59,7 @@ var resolveTimeout = 10 * time.Second
59
60
// P2PCmd is the 'ipfs p2p' command
61
var P2PCmd = &cmds.Command{
62
+ Status: cmds.Experimental,
63
Helptext: cmds.HelpText{
64
Tagline: "Libp2p stream mounting.",
65
ShortDescription: `
@@ -78,6 +79,7 @@ are refined`,
79
}
80
81
var p2pForwardCmd = &cmds.Command{
82
+ Status: cmds.Experimental,
83
Helptext: cmds.HelpText{
84
Tagline: "Forward connections to libp2p service.",
85
ShortDescription: `
@@ -179,6 +181,7 @@ func parseIpfsAddr(addr string) (*peer.AddrInfo, error) {
181
}
182
183
var p2pListenCmd = &cmds.Command{
184
+ Status: cmds.Experimental,
185
Helptext: cmds.HelpText{
186
Tagline: "Create libp2p service.",
187
ShortDescription: `
@@ -280,6 +283,7 @@ const (
283
)
284
285
var p2pLsCmd = &cmds.Command{
286
+ Status: cmds.Experimental,
287
Helptext: cmds.HelpText{
288
Tagline: "List active p2p listeners.",
289
},
@@ -343,6 +347,7 @@ const (
347
)
348
349
var p2pCloseCmd = &cmds.Command{
350
+ Status: cmds.Experimental,
351
Helptext: cmds.HelpText{
352
Tagline: "Stop listening for new connections to forward.",
353
},
@@ -427,6 +432,7 @@ var p2pCloseCmd = &cmds.Command{
432
433
// p2pStreamCmd is the 'ipfs p2p stream' command
434
var p2pStreamCmd = &cmds.Command{
435
+ Status: cmds.Experimental,
436
Helptext: cmds.HelpText{
437
Tagline: "P2P stream management.",
438
ShortDescription: "Create and manage p2p streams",
@@ -439,6 +445,7 @@ var p2pStreamCmd = &cmds.Command{
445
}
446
447
var p2pStreamLsCmd = &cmds.Command{
448
+ Status: cmds.Experimental,
449
Helptext: cmds.HelpText{
450
Tagline: "List active p2p streams.",
451
},
@@ -488,6 +495,7 @@ var p2pStreamLsCmd = &cmds.Command{
495
}
496
497
var p2pStreamCloseCmd = &cmds.Command{
498
+ Status: cmds.Experimental,
499
Helptext: cmds.HelpText{
500
Tagline: "Close active p2p stream.",
501
},
core/commands/pubsub.go
+5
@@ -17,6 +17,7 @@ import (
17
)
18
19
var PubsubCmd = &cmds.Command{
20
+ Status: cmds.Experimental,
21
Helptext: cmds.HelpText{
22
Tagline: "An experimental publish-subscribe system on ipfs.",
23
ShortDescription: `
@@ -46,6 +47,7 @@ type pubsubMessage struct {
47
}
48
49
var PubsubSubCmd = &cmds.Command{
50
+ Status: cmds.Experimental,
51
Helptext: cmds.HelpText{
52
Tagline: "Subscribe to messages on a given topic.",
53
ShortDescription: `
@@ -144,6 +146,7 @@ TOPIC AND DATA ENCODING
146
}
147
148
var PubsubPubCmd = &cmds.Command{
149
+ Status: cmds.Experimental,
150
Helptext: cmds.HelpText{
151
Tagline: "Publish data to a given pubsub topic.",
152
ShortDescription: `
@@ -199,6 +202,7 @@ HTTP RPC ENCODING
202
}
203
204
var PubsubLsCmd = &cmds.Command{
205
+ Status: cmds.Experimental,
206
Helptext: cmds.HelpText{
207
Tagline: "List subscribed topics by name.",
208
ShortDescription: `
@@ -270,6 +274,7 @@ func safeTextListEncoder(req *cmds.Request, w io.Writer, list *stringList) error
274
}
275
276
var PubsubPeersCmd = &cmds.Command{
277
+ Status: cmds.Experimental,
278
Helptext: cmds.HelpText{
279
Tagline: "List peers we are currently pubsubbing with.",
280
ShortDescription: `
core/commands/repo.go
+1
@@ -222,6 +222,7 @@ Version string The repo version.
222
}
223
224
var repoFsckCmd = &cmds.Command{
225
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/issues/6435
226
Helptext: cmds.HelpText{
227
Tagline: "Remove repo lockfiles.",
228
ShortDescription: `
core/commands/unixfs/ls.go
+2
-1
@@ -33,8 +33,9 @@ type LsOutput struct {
33
}
34
35
var LsCmd = &cmds.Command{
36
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/pull/7755
37
Helptext: cmds.HelpText{
37
- Tagline: "List directory contents for Unix filesystem objects. Deprecated: Use 'ipfs ls' instead.",
38
+ Tagline: "List directory contents for Unix filesystem objects. Deprecated: Use 'ipfs ls' and 'ipfs files ls' instead.",
39
ShortDescription: `
40
Displays the contents of an IPFS or IPNS object(s) at the given path.
41
core/commands/unixfs/unixfs.go
+3
-8
@@ -5,17 +5,12 @@ import (
5
)
6
7
var UnixFSCmd = &cmds.Command{
8
+ Status: cmds.Deprecated, // https://github.com/ipfs/go-ipfs/pull/7755
9
Helptext: cmds.HelpText{
10
Tagline: "Interact with IPFS objects representing Unix filesystems.",
11
ShortDescription: `
11
-'ipfs file' provides a familiar interface to file systems represented
12
-by IPFS objects, which hides ipfs implementation details like layout
13
-objects (e.g. fanout and chunking).
14
-`,
15
- LongDescription: `
16
-'ipfs file' provides a familiar interface to file systems represented
17
-by IPFS objects, which hides ipfs implementation details like layout
18
-objects (e.g. fanout and chunking).
12
+Old interface to file systems represented by UnixFS.
13
+Superseded by modern alternatives: 'ipfs ls' and 'ipfs files'
14
`,
15
},
16
core/commands/urlstore.go
+1
@@ -23,6 +23,7 @@ var urlStoreCmd = &cmds.Command{
23
}
24
25
var urlAdd = &cmds.Command{
26
+ Status: cmds.Deprecated,
27
Helptext: cmds.HelpText{
28
Tagline: "Add URL via urlstore.",
29
LongDescription: `
go.mod
+1
-1
@@ -31,7 +31,7 @@ require (
31
github.com/ipfs/go-graphsync v0.11.0
32
github.com/ipfs/go-ipfs-blockstore v1.2.0
33
github.com/ipfs/go-ipfs-chunker v0.0.5
34
- github.com/ipfs/go-ipfs-cmds v0.6.0
34
+ github.com/ipfs/go-ipfs-cmds v0.7.0
35
github.com/ipfs/go-ipfs-exchange-interface v0.1.0
36
github.com/ipfs/go-ipfs-exchange-offline v0.2.0
37
github.com/ipfs/go-ipfs-files v0.0.9
go.sum
+2
-2
@@ -473,8 +473,8 @@ github.com/ipfs/go-ipfs-blocksutil v0.0.1/go.mod h1:Yq4M86uIOmxmGPUHv/uI7uKqZNtL
473
github.com/ipfs/go-ipfs-chunker v0.0.1/go.mod h1:tWewYK0we3+rMbOh7pPFGDyypCtvGcBFymgY4rSDLAw=
474
github.com/ipfs/go-ipfs-chunker v0.0.5 h1:ojCf7HV/m+uS2vhUGWcogIIxiO5ubl5O57Q7NapWLY8=
475
github.com/ipfs/go-ipfs-chunker v0.0.5/go.mod h1:jhgdF8vxRHycr00k13FM8Y0E+6BoalYeobXmUyTreP8=
476
-github.com/ipfs/go-ipfs-cmds v0.6.0 h1:yAxdowQZzoFKjcLI08sXVNnqVj3jnABbf9smrPQmBsw=
477
-github.com/ipfs/go-ipfs-cmds v0.6.0/go.mod h1:ZgYiWVnCk43ChwoH8hAmI1IRbuVtq3GSTHwtRB/Kqhk=
476
+github.com/ipfs/go-ipfs-cmds v0.7.0 h1:0lEldmB7C83RxIOer38Sv1ob6wIoCAIEOaxiYgcv7wA=
477
+github.com/ipfs/go-ipfs-cmds v0.7.0/go.mod h1:y0bflH6m4g6ary4HniYt98UqbrVnRxmRarzeMdLIUn0=
478
github.com/ipfs/go-ipfs-delay v0.0.0-20181109222059-70721b86a9a8/go.mod h1:8SP1YXK1M1kXuc4KJZINY3TQQ03J2rwBG9QfXmbRPrw=
479
github.com/ipfs/go-ipfs-delay v0.0.1 h1:r/UXYyRcddO6thwOnhiznIAiSvxMECGgtv35Xs1IeRQ=
480
github.com/ipfs/go-ipfs-delay v0.0.1/go.mod h1:8SP1YXK1M1kXuc4KJZINY3TQQ03J2rwBG9QfXmbRPrw=