Common subcommand naming scheme (#208)

drop tea mile alias

document command schema in CONTRIBUTING.md

and update this file, its a plain copy from gitea

add "list" as alias for "ls" subcommand

add singular command aliases

Co-authored-by: Norwin Roosen <git@nroo.de>
Reviewed-on: https://gitea.com/gitea/tea/pulls/208
Reviewed-by: 6543 <6543@noreply.gitea.io>
Reviewed-by: techknowlogick <techknowlogick@gitea.io>

CONTRIBUTING.md

@@ -8,7 +8,6 @@
   - [Discuss your design](#discuss-your-design)
   - [Testing redux](#testing-redux)
   - [Vendoring](#vendoring)
-  - [Translation](#translation)
   - [Code review](#code-review)
   - [Styleguide](#styleguide)
   - [Sign-off your work](#sign-off-your-work)
@@ -21,12 +20,10 @@
 ## Introduction
 
 This document explains how to contribute changes to the Gitea project.
-It assumes you have followed the
-[installation instructions](https://docs.gitea.io/en-us/).
 Sensitive security-related issues should be reported to
 [security@gitea.io](mailto:security@gitea.io).
 
-For configuring IDE or code editor to develop Gitea see [IDE and code editor configuration](contrib/ide/)
+For configuring IDE or code editor to develop Gitea see [IDE and code editor configuration](https://github.com/go-gitea/gitea/tree/master/contrib/ide)
 
 ## Bug reports
 
@@ -49,7 +46,7 @@ getting free help.
 ## Discuss your design
 
 The project welcomes submissions. If you want to change or add something,
-please let everyone know what you're working on—[file an issue](https://github.com/go-gitea/gitea/issues/new)!
+please let everyone know what you're working on—[file an issue](https://gitea.com/gitea/tea/issues/new)!
 Significant changes must go through the change proposal process
 before they can be accepted. To create a proposal, file an issue with
 your proposed changes documented, and make sure to note in the title
@@ -87,16 +84,7 @@ an existing upstream commit.
 
 You can find more information on how to get started with it on the [dep project website](https://golang.github.io/dep/docs/introduction.html).
 
-## Translation
-
-We do all translation work inside [Crowdin](https://crowdin.com/project/gitea).
-The only translation that is maintained in this git repository is
-[`en_US.ini`](https://github.com/go-gitea/gitea/blob/master/options/locale/locale_en-US.ini)
-and is synced regularily to Crowdin. Once a translation has reached
-A SATISFACTORY PERCENTAGE it will be synced back into this repo and
-included in the next released version.
-
-## Building Gitea
+## Building tea
 
 Generally, the go build tools are installed as-needed in the `Makefile`.
 An exception are the tools to build the CSS and images.
@@ -128,6 +116,27 @@ Some of the key points:
 
 ## Styleguide
 
+### Command naming
+- Subcommands should follow the following structure:
+    ```
+    tea <noun> <verb> [<noun>] [<flags>]
+    ```
+
+    for example:
+
+    ```
+    tea issues list
+    tea pulls create
+    tea teams add user --team x --user y
+    ```
+- Commands should accept nouns as singular & plural by making use of the `Aliases` field.
+- The default action without a verb is `list`.
+- `list` commands always apply pagination where provided by the API.
+- Try to reuse as many flag definitions as possible, see `cmd/flags.go`.
+- Always make sure that the help texts are properly set, and as concise as possible.
+
+### Code style
+Use `go fmt`, check with `make lint`.
 For imports you should use the following format (_without_ the comments)
 ```go
 import (
@@ -245,7 +254,7 @@ they served:
 
 ## Versions
 
-Gitea has the `master` branch as a tip branch and has version branches
+tea has the `master` branch as a tip branch and has version branches
 such as `release/v0.9`. `release/v0.9` is a release branch and we will
 tag `v0.9.0` for binary download. If `v0.9.0` has bugs, we will accept
 pull requests on the `release/v0.9` branch and publish a `v0.9.1` tag,

cmd/issues.go

@@ -17,6 +17,7 @@ import (
 // CmdIssues represents to login a gitea server.
 var CmdIssues = cli.Command{
 	Name:        "issues",
+	Aliases:     []string{"issue"},
 	Usage:       "List, create and update issues",
 	Description: "List, create and update issues",
 	ArgsUsage:   "[<issue index>]",

cmd/issues/list.go

@@ -19,6 +19,7 @@ import (
 // CmdIssuesList represents a sub command of issues to list issues
 var CmdIssuesList = cli.Command{
 	Name:        "ls",
+	Aliases:     []string{"list"},
 	Usage:       "List issues of the repository",
 	Description: `List issues of the repository`,
 	Action:      RunIssuesList,

cmd/labels.go

@@ -23,6 +23,7 @@ import (
 // CmdLabels represents to operate repositories' labels.
 var CmdLabels = cli.Command{
 	Name:        "labels",
+	Aliases:     []string{"label"},
 	Usage:       "Manage issue labels",
 	Description: `Manage issue labels`,
 	Action:      runLabels,

cmd/login.go

@@ -12,7 +12,8 @@ import (
 
 // CmdLogin represents to login a gitea server.
 var CmdLogin = cli.Command{
-	Name:        "login",
+	Name:        "logins",
+	Aliases:     []string{"login"},
 	Usage:       "Log in to a Gitea server",
 	Description: `Log in to a Gitea server`,
 	Action:      login.RunLoginAddInteractive, // TODO show list if no arg & detail if login as arg

cmd/login/list.go

@@ -18,6 +18,7 @@ import (
 // CmdLoginList represents to login a gitea server.
 var CmdLoginList = cli.Command{
 	Name:        "ls",
+	Aliases:     []string{"list"},
 	Usage:       "List Gitea logins",
 	Description: `List Gitea logins`,
 	Action:      runLoginList,

cmd/milestones.go

@@ -16,7 +16,7 @@ import (
 // CmdMilestones represents to operate repositories milestones.
 var CmdMilestones = cli.Command{
 	Name:        "milestones",
-	Aliases:     []string{"ms", "mile"},
+	Aliases:     []string{"milestone", "ms"},
 	Usage:       "List and create milestones",
 	Description: `List and create milestones`,
 	ArgsUsage:   "[<milestone name>]",

cmd/milestones/list.go

@@ -19,6 +19,7 @@ import (
 // CmdMilestonesList represents a sub command of milestones to list milestones
 var CmdMilestonesList = cli.Command{
 	Name:        "ls",
+	Aliases:     []string{"list"},
 	Usage:       "List milestones of the repository",
 	Description: `List milestones of the repository`,
 	Action:      RunMilestonesList,

cmd/notifications.go

@@ -19,7 +19,7 @@ import (
 // CmdNotifications is the main command to operate with notifications
 var CmdNotifications = cli.Command{
 	Name:        "notifications",
-	Aliases:     []string{"notif"},
+	Aliases:     []string{"notification", "notif"},
 	Usage:       "Show notifications",
 	Description: "Show notifications, by default based of the current repo and unread one",
 	Action:      runNotifications,

cmd/pulls/list.go

@@ -19,6 +19,7 @@ import (
 // CmdPullsList represents a sub command of issues to list pulls
 var CmdPullsList = cli.Command{
 	Name:        "ls",
+	Aliases:     []string{"list"},
 	Usage:       "List pull requests of the repository",
 	Description: `List pull requests of the repository`,
 	Action:      RunPullsList,

cmd/releases.go

@@ -14,8 +14,8 @@ import (
 // CmdReleases represents to login a gitea server.
 // ToDo: ReleaseDetails
 var CmdReleases = cli.Command{
-	Name:        "release",
-	Aliases:     []string{"releases"},
+	Name:        "releases",
+	Aliases:     []string{"release"},
 	Usage:       "Manage releases",
 	Description: "Manage releases",
 	Action:      releases.RunReleasesList,

cmd/releases/list.go

@@ -19,6 +19,7 @@ import (
 // CmdReleaseList represents a sub command of Release to list releases
 var CmdReleaseList = cli.Command{
 	Name:        "ls",
+	Aliases:     []string{"list"},
 	Usage:       "List Releases",
 	Description: "List Releases",
 	Action:      RunReleasesList,

cmd/repos.go

@@ -18,8 +18,9 @@ import (
 // CmdRepos represents to login a gitea server.
 var CmdRepos = cli.Command{
 	Name:        "repos",
-	Usage:       "Show repositories details",
-	Description: "Show repositories details",
+	Aliases:     []string{"repo"},
+	Usage:       "Show repository details",
+	Description: "Show repository details",
 	ArgsUsage:   "[<repo owner>/<repo name>]",
 	Action:      runRepos,
 	Subcommands: []*cli.Command{

cmd/repos/list.go

@@ -20,6 +20,7 @@ import (
 // CmdReposList represents a sub command of repos to list them
 var CmdReposList = cli.Command{
 	Name:        "ls",
+	Aliases:     []string{"list"},
 	Usage:       "List available repositories",
 	Description: `List available repositories`,
 	Action:      RunReposList,