Command naming consistency

[0x2b3bfa0]

Unify naming without breaking backwards compatibility.

• more intuitive (e.g. cml <noun> <verb> [options])
• easier to explain
• better correspondence with (to be) documented use cases

Current	Proposed
cml ci	cml ci [setup]
cml pr	cml pr [create] [{--merge,--rebase,--squash}]
	cml pr {create <file...>,close [<number>]}
	cml pr {merge} [{--no-ff(?),--ff(?),--rebase,--squash}]
cml publish [--native] [--type=file]	hide
cml runner	cml runner [launch]
cml send-comment	cml {comment,report} {create,update}
	cml {comment,report} watch [--update]
cml send-github-check	cml check {create,update}
cml tensorboard-dev	cml tensorboard-dev [publish]
cml rerun-workflow	cml workflow {rerun,stop}

See also

• https://primer.style/cli/foundations/language
• https://github.com/spf13/cobra#concepts

Related

• cml pr: Add --merge option. #823 (comment)
• Integrate cml publish with cml send-comment #1026 (comment) — unify trailing periods on --help messages

[casperdcl]

s/attachment/attach/

[0x2b3bfa0]

s/attachment/attach/

Is attach a noun? 🤔 https://dictionary.cambridge.org/dictionary/english/attach

[casperdcl]

I wasn't following noun convention. Now that I think of it, I was assuming verb for simple commands and noun for complex ones... So they're all (possibly abbreviated) verbs apart from runner

[0x2b3bfa0]

I don't think verbs are appropriate for the top–level command names:

• p[ull]r[equest] as a verb is fairly uncommon
• attachment or image should be consistent with the others
• comment is both verb and noun, so it doesn't matter
• check does not “check” anything, but rather create a check on the repository
• runner registers a runner, and shouldn't be abbreviated as run or something equally attrocious

[DavidGOrtega]

attachment or image should be consistent with the others
👎

Im not a super fan of publish but attachment or image is... really bad 😁

[DavidGOrtega]

p[ull]r[equest] as a verb is fairly uncommon, at least for the people I know

but other commands start with a verb

Does not need to reflect a verb necessarily but the final outcome as cml comment does not need to be the comment as a verb but the comment as an entity as @casperdcl also manifest

[DavidGOrtega]

• pr generates a PR
• comment generates a comment
• check generates a check
• runner generates a runner
• tensorboard-dev generates a resource at tb dev

then we have publish. The outsider... media file resource asset?

[casperdcl]

I don't think verbs are appropriate

strictly it's about being an imperative/action: X now! so the only outliers are:

• runner -> runner {launch,create}
• tensorboard-dev -> tensorboard {dev,push,link,connect,publish...}

I suppose we could try publish {image,tensorboard,...}.

[DavidGOrtega]

cml runner comes from cml_runner that means cml's runner to my mind. Seems that the cml command has brought the pandora's box about naming.

Ideally speaking cml should probably be:

cml reports comment/publish/ 
cml runner
...

however I fully understand that cml is an entity that can generate a resource

cml resource