Define a standardized command syntax #37

Closed
opened 2019-06-09 13:00:02 +00:00 by ngourdon · 4 comments

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:

  • tea name ls: list items
  • tea name show: show an item
  • tea name create: create an item
  • tea name edit: edit an item
  • tea name rm: remove an item

The name should be in singular form.

There could be multiple nested names: tea repo collaborator ls

create command could be change by add in some context:
tea repo create but tea repo collaborator add

Other action verb could be defined for other needs.

Changes

By following this proposal guidelines, existing commands will change to:

  • tea issue ls
  • tea issue create
  • tea pull ls
  • tea release ls

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.

### 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: - tea name ls: list items - tea name show: show an item - tea name create: create an item - tea name edit: edit an item - tea name rm: remove an item The name should be in singular form. There could be multiple nested names: `tea repo collaborator ls` `create` command could be change by `add` in some context: `tea repo create` but `tea repo collaborator add` Other action verb could be defined for other needs. ### Changes By following this proposal guidelines, existing commands will change to: - tea issue ls - tea issue create - tea pull ls - tea release ls ### 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.
lunny added the
kind/proposal
label 2019-06-09 13:34:59 +00:00
Owner

Currently

  • tea issues
  • tea issues create
  • tea pulls
  • tea pulls create

Don't you think it's also obey some rules?

Currently - tea issues - tea issues create - tea pulls - tea pulls create Don't you think it's also obey some rules?
Author

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: list issues or show the details of one issue
  • tea issues ls: list issues
  • tea issues create: create a new issue
  • tea releases: list releases
  • tea releases create: create a new release
  • tea pulls: list pull requests

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 and tea issues show

or

  • tea issue ls and tea 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.

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: list issues or show the details of one issue - tea issues ls: list issues - tea issues create: create a new issue - tea releases: list releases - tea releases create: create a new release - tea pulls: list pull requests `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` and `tea issues show` or - `tea issue ls` and `tea 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.
Member

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 and issue 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 but tea 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 not ls for clarity.

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``` and ```issue``` 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 but ```tea 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 not ```ls``` for clarity.
Member

AFAIK, a goal for tea was to be a drop-in replacement for hub (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).

AFAIK, a goal for `tea` was to be a drop-in replacement for [`hub`](https://hub.github.com) (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).
6543 changed title from Proposal: Define a standardized command syntax to Define a standardized command syntax 2020-07-16 12:43:44 +00:00
noerw added the
kind
refactor
label 2020-09-30 07:01:29 +00:00
noerw added the
status/has-pull
label 2020-10-02 10:29:17 +00:00
6543 closed this issue 2020-10-02 15:46:53 +00:00
Sign in to join this conversation.
No Milestone
No Assignees
4 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: gitea/tea#37
No description provided.