Define a standardized command syntax #37
Labels
No Label
kind/breaking
kind/bug
kind/build
kind/dependency
kind/deployment
kind/docs
kind
enhancement
kind
feature
kind/proposal
kind
question
kind
refactor
kind/security
kind/testing
kind/translation
priority/critical
priority/high
priority/low
priority/medium
reviewed/duplicate
reviewed/invalid
reviewed/wontfix
skip-changelog
status/blocked
status/has-backport
status/has-pull
status/needs-backport
status/needs-feedback
status/needs-reviews
status/wip
upstream/gitea
upstream/sdk
No Milestone
No Assignees
4 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: gitea/tea#37
Loading…
Reference in New Issue
Block a user
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Description
Currently, few commands exist but there's already some differences between issues commands and pulls/releases commands.
To ease the adding of new commands and have consistency between them, we should define guidelines to commands syntax and how to organize them IMHO.
Proposal
The commands should follow the syntax:
The name should be in singular form.
There could be multiple nested names:
tea repo collaborator ls
create
command could be change byadd
in some context:tea repo create
buttea repo collaborator add
Other action verb could be defined for other needs.
Changes
By following this proposal guidelines, existing commands will change to:
Summary
The goal of the proposed changes is to provide an easy to use syntax for the user and guidelines for collaborators to add new commands.
Any improvements are welcome.
Thanks for your feedbacks.
Currently
Don't you think it's also obey some rules?
Sure it does. The proposal is not far from what it is curently done.
Currently, not all commands follow the rules you stated:
tea issues
: depending on the parameters list issues or show the details of one issue.imho I think it could be better if we have two commands:
tea issues
andtea issues show
or
tea issue ls
andtea issue show
I prefer the second one, see below.
The use of plural names seems natural for commands that list the issues, pulls or releases. For other commands, it does not imho.
I made this proposal to open discussion.
The proposal will be improved with feedbacks like yours to end up with something we could agree on.
Agree this sounds good. I think wp-cli tool can be a good example of something that has many commands (and allows for custom commands) while trying to keep some sort of standard:
https://make.wordpress.org/cli/handbook/quick-start/
They also have similar issue of plural vs not (plugin instead of plugins) and decided to just use the singular form which I thought was a little awkward at first but got used to very quickly and don't think about now. This tools is very popular and used by lots of small and large companies so I think the design is proven to be OK in that sense.
I think whatever choice would be fine as long as it is only one for each category -- ie we should not have both
issues
andissue
as supported commands.I also like how each category does nothing when run on its own, but requires an explicit command.
So
tea issues
would just show you the help menu/options buttea issues list
will list the issues. That means you always know what is going to happen when a command is run because you have to be specific on what it should do.I also would prefer we should use
list
and notls
for clarity.AFAIK, a goal for
tea
was to be a drop-in replacement forhub
(GitHub's CLI) at least as reasonably possible.While I support documenting a unified command naming scheme, we should keep that goal in mind (or discuss it as well).
Re:
ls
subcommand: I personally think doing a listing if no verb is provided is a good default (makes command iteration faster), though I can see that the CLI feels "safer" if no action is ever made without a verb.Re: singular or plural nouns:
hub
uses singular. I guess this is quite opinionated (I personally like plurals), so we'll have always people typing wrong commands. I don't see why we shouldn't alias these commands to have both available. (urfave/cli
has command aliases built in btw).noerw referenced this issue2019-10-25 09:25:07 +00:00
noerw referenced this issue2019-10-25 09:25:22 +00:00
noerw referenced this issue2019-10-25 09:25:31 +00:00
noerw referenced this issue2019-10-25 09:26:47 +00:00
noerw referenced this issue2019-10-25 09:29:33 +00:00
noerw referenced this issue2019-10-25 09:30:59 +00:00
Proposal: Define a standardized command syntaxto Define a standardized command syntax