change names of ipfs dag put flags to make changes clearer

[aschmahmann]

Proposed changes for #8415

[lidel]

Looks sensible, I would shorten store-codec to codec to indicate it is THE codec,
but not feeling too strong either way.

cc @warpfork if any concerns (context: we need to change names to ensure people are not hit by silent bugs caused byt the change around cbor/dag-cbor and json/dag-json, which may produces different CID in some cases)

[aschmahmann]

Don't feel too strongly about store-codec vs codec here, figured more text might be more informative but we could also throw that in the help text.

I tried using codec in #8440 (comment). However, we can't use -c as a shortcut because it's already taken by --config on the global ipfs command. Any thoughts on the name in #8440 and here, as well as if there should be a shortcut name?

[warpfork]

I think I'm gonna studiously not have an opinion this (at least, today).

If I were going to have an opinion, I'd start forming it by sketching a new command family, and make sure I can draft the whole family at once, and make sure things are internally consistent and follow some rule. I'd draft some examples (just to get my brain working on the concretes), then document the rule (this is the important part), and only then finish implementing and do final consistency review on the commands. (And to put my time/money where my mouth is at: I started drafting some new CLI tools in another repo, where I'm going to do that, in that order. That's gonna cook for a while, though.)

If we're going to do something about the ipfs dag commands, a similar approach could be useful. I'd be careful of patching one ipfs dag * subcommand at a time. If we want to minimize surprise of new end-users, it's the whole subcommand family that should have some holistic rule that it follows. (If we want to minimize the surprise of existing end-users of this API: I have no idea, I'm not one of them.)

And I don't know where I sit on the topic of whether it's worth changing these at all, vs just drafting generationally new APIs. My 2c is that it's often a lot easier/higher-leverage to draft generationally new things (lets you fix families of problems; also lets you maintain the old one with less change until you sunset it). But in the go-ipfs repo, that's not my choice to make.

[lidel]

Regarding the blast radius of the decision made here, AFAIK impacted commands are only dag put and dag get (and maybe future patch (#4782) and diff (#4801) operations).

I played with different notations, and IMO the value of short notation is debatable: most of the time defaults are fine, and when one needs to override them, longer notation is less prone to typos and errors are easier to catch.

👉 My suggestion is to go with clean --input-codec and --codec (without any shortcuts).

[ribasushi]

I played with different notations, and IMO the value of short notation is debatable: most of the time defaults are fine, and when one needs to override them, longer notation is less prone to typos and errors are easier to catch.
👉 My suggestion is to go with clean --input-codec and --codec (without any shortcuts).

I concur with dropping the shortcuts/single-letter-options.

I am less certain about going with --input-codec / --codec. While yes, other systems use --codec throughout, they do not do "translation" level stuff. I think having a symmetric --input-codec / --store-codec ( and maybe even --output-codec in the future ), while clunky, is the right way to go...

[warpfork]

I guess if anything is to change here, I probably agree with @ribasushi 's suggestion that things be explicit about input direction and output direction, and we pretty much tacitly never use the word "codec" bare without a directional indicator. One of the big issues with these commands and their flags as they stand now are that people get very confused which phase a codec is applied at, so if we're changing anything, it seems we should increasingly favor explicitness.

Maybe some other commands only have one direction or the other, sure. But I bet it will still be clearer overall to have those commands have a longer flag just to be consistent with anything that does have flags for multiple phases of data flow.

[aschmahmann]

Latest update: We're going to use --input-codec and --store-codec here, and ipfs dag get will use --output-codec. For now we will not be using shortcuts, we can see if there ends up being significant demand for them.