cml Command naming consistency

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}`

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

Oct 12 '21 22:10 0x2b3bfa0

attachment or image should be consistent with the others 👎

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

Oct 13 '21 11:10 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

Oct 13 '21 11:10 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?

Oct 13 '21 11:10 DavidGOrtega

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,...}.

Oct 13 '21 12:10 casperdcl

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

Oct 13 '21 12:10 DavidGOrtega

Updated description to be cml noun... [--mutex-action-verb]. With aliases, this retains backwards-compatibility
I'd also say default-verbs don't need be implemented (e.g. cml pr without flags obviously implies create, so we don't need to support an explicit create subcommand).

Dec 07 '21 11:12 casperdcl

TL;DR for now we should do:

send-comment -> {comment,report} [{--create,--update}]
rerun-workflow -> workflow [--rerun]

but keep backward-compatibility

May 26 '22 18:05 casperdcl

If we're supporting actions other than create commands should be in the form cml noun verb --modifier instead of cml noun --verb --modifier as @casperdcl proposed.

If there isn't any command supporting verbs other than create we may make it implicit as well, and have cml noun --modifier

Jun 04 '22 18:06 0x2b3bfa0

cml noun verb[implied create] --modifier +1

Jun 04 '22 19:06 dacbd

Hmm. cml report [create] won't work. create will have to be <required> (not [optional]) due to the next arg also being a <positional>: cml comment {create,update} <report.md>.

Isn't cml comment [{--create,--update}] <report.md> nicer?

Jun 06 '22 18:06 casperdcl

Isn't cml comment [{--create,--update}] <report.md> nicer?

🐻👨🏼‍🍳🤺 No strong opinions on this but things get a bit messy when using --options both for verbs and modifiers. E.g. cml report --update --pr --commit-sha=2b3bfa0 🤔

Jun 06 '22 22:06 0x2b3bfa0

Anyway, my biggest concern is extensibility. For the current command set, it doesn't look that bad.

Jun 06 '22 22:06 0x2b3bfa0

Request for ~last will~ comments

Current	Proposed
`cml ci`	`cml ci setup`
`cml pr`	`cml pr create <file...>`
	`cml pr close [number]`
	`cml pr merge [--rebase\|--squash]`
`cml publish`	hidden, superseded by `cml report`[^1]
`cml rerun-workflow`	`cml workflow <restart\|stop>`
`cml runner`	`cml runner [start]`[^2]
`cml send-comment`	`cml report <create\|update>`
`cml send-github-check`	`cml check <create\|update>`
`cml tensorboard-dev`	`cml tensorboard start`

Philosophical question: are checks and comments two different kinds of report?

[^1]: Since there are no external uses for cml publish beyond cml report and cml check and #1026 eliminates the need for a separate command [^2]: While register/unregister is semantically equivalent to create/delete, the unregister part is not exposed to users, and start feels more natural; i.e. same fire-and-forget behavior as cml tensorboard start

Jun 15 '22 19:06 0x2b3bfa0

cml runner [start] ?

Jun 16 '22 14:06 dacbd

Surely cml pr [create] -> cml pr create?

Jun 17 '22 03:06 casperdcl

bumping priority on this (blocking everything from https://github.com/iterative/cml/pull/1026#discussion_r901479836 to https://github.com/iterative/cml.dev/issues/250).

Updated the OP in light of last ~will~ comments.

Jun 20 '22 10:06 casperdcl

I see 3 points of contention, can vote with emojis:

cml runner a) [launch] :+1: b) [start] :eyes:
cml tensorboard-dev a) [publish] :smile: b) [start] :tada:
cml workflow a) rerun :heart: b) restart :rocket:

Jun 20 '22 10:06 casperdcl

🛎️ @iterative/cml: philosophical question (bis): are checks and comments two different kinds of report?

Jun 22 '22 19:06 0x2b3bfa0

How is cml <report|check> create different from cml <report|check> update in behavior? Doesn't the latter imply the former?[^1] Would it make more sense to provide cml <report|check> create --update instead?

[^1]: i.e. for practical reasons, update means create if not exists, update otherwise

Jun 22 '22 19:06 0x2b3bfa0

btw https://cli.github.com/manual/gh_run_rerun & https://cli.github.com/manual/gh_workflow_run strongly implies (3a:heart:) beats (3b:rocket:)
report create vs report update - yes, they are different. "Create" always makes a new comment, "update" tries to edit an existing comment
report create --update seems as illogical to me as s/workflow rerun/workflow run --rerun/

Jun 22 '22 20:06 casperdcl

"update" tries to edit an existing comment

And what happens if there isn't an existing comment to edit?

Jun 23 '22 14:06 0x2b3bfa0

How is cml <report|check> create different from cml <report|check> update in behavior? Doesn't the latter imply the former?1 Would it make more sense to provide cml <report|check> create --update instead?

check should be able to offer the capability of automatically guessing the status with code checks, like deepchecks or easy comparator s over dvc diff metrics...

Jun 23 '22 14:06 DavidGOrtega

Follow-up https://github.com/iterative/cml/pull/1026#discussion_r901479836 probably required.

Jun 23 '22 17:06 0x2b3bfa0

what happens if there isn't an existing comment to edit?

Same as what's already implemented right now: fallback to create

Jun 24 '22 09:06 casperdcl

Then, is a separate update verb really needed? 🤔 It's more like create and createorupdate

Jun 24 '22 10:06 0x2b3bfa0

Yes, exactly. Strong preference for

consistency (cml <noun> <verb> [options])
conciseness ("update: updates existing CML comment, falling back to create if none exists" is fine to document IMO, while createorupdate is clunky and requires precisely the same docstring anyway.)

So it must be cml report {create,read,update,delete}, right?

Jun 24 '22 12:06 casperdcl

Command naming consistency

See also

Related