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

[casperdcl]

1. Updated description to be cml noun... [--mutex-action-verb]. With aliases, this retains backwards-compatibility
2. 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).

[0x2b3bfa0]

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

[dacbd]

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

[casperdcl]

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?

[0x2b3bfa0]

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 🤔

[0x2b3bfa0]

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

[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 report1
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?

Footnotes

1. Since there are no external uses for cml publish beyond cml report and cml check and Integrate cml publish with cml send-comment #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 ↩

[dacbd]

cml runner [start] ?

[casperdcl]

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

[casperdcl]

bumping priority on this (blocking everything from #1026 (comment) to iterative/cml.dev#250).

Updated the OP in light of last will comments.

[casperdcl]

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

1. cml runner
   a) [launch] 👍
   b) [start] 👀
2. cml tensorboard-dev
   a) [publish] 😄
   b) [start] 🎉
3. cml workflow
   a) rerun ❤️
   b) restart 🚀

[0x2b3bfa0]

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

[0x2b3bfa0]

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

Footnotes

1. i.e. for practical reasons, update means create if not exists, update otherwise ↩

[casperdcl]

• 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/

[0x2b3bfa0]

"update" tries to edit an existing comment

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

[DavidGOrtega]

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

[0x2b3bfa0]

Follow-up #1026 (comment) probably required.

[casperdcl]

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

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

[0x2b3bfa0]

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

[casperdcl]

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?

[0x2b3bfa0]

createorupdate is clunky

Clarification: I never meant to have a verb named createorupdate; I used that string only for the sake of clarity on this conversation.

[0x2b3bfa0]

Avoid making modifiers their own commands

Can --update be regarded as a modifier?

[casperdcl]

Not to me. Seems same level as "create" (vis. the CRUD acronym)