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>
This commit is contained in:
Norwin 2020-10-02 15:46:51 +00:00 committed by 6543
parent f5dbd44ebe
commit 3ee5501257
14 changed files with 43 additions and 24 deletions

View File

@ -8,7 +8,6 @@
- [Discuss your design](#discuss-your-design) - [Discuss your design](#discuss-your-design)
- [Testing redux](#testing-redux) - [Testing redux](#testing-redux)
- [Vendoring](#vendoring) - [Vendoring](#vendoring)
- [Translation](#translation)
- [Code review](#code-review) - [Code review](#code-review)
- [Styleguide](#styleguide) - [Styleguide](#styleguide)
- [Sign-off your work](#sign-off-your-work) - [Sign-off your work](#sign-off-your-work)
@ -21,12 +20,10 @@
## Introduction ## Introduction
This document explains how to contribute changes to the Gitea project. 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 Sensitive security-related issues should be reported to
[security@gitea.io](mailto:security@gitea.io). [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 ## Bug reports
@ -49,7 +46,7 @@ getting free help.
## Discuss your design ## Discuss your design
The project welcomes submissions. If you want to change or add something, 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 Significant changes must go through the change proposal process
before they can be accepted. To create a proposal, file an issue with 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 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). 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 ## Building tea
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
Generally, the go build tools are installed as-needed in the `Makefile`. Generally, the go build tools are installed as-needed in the `Makefile`.
An exception are the tools to build the CSS and images. An exception are the tools to build the CSS and images.
@ -128,6 +116,27 @@ Some of the key points:
## Styleguide ## 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) For imports you should use the following format (_without_ the comments)
```go ```go
import ( import (
@ -202,7 +211,7 @@ to the maintainers team. If a maintainer is inactive for more than 3
months and forgets to leave the maintainers team, the owners may move months and forgets to leave the maintainers team, the owners may move
him or her from the maintainers team to the advisors team. him or her from the maintainers team to the advisors team.
For security reasons, Maintainers should use 2FA for their accounts and For security reasons, Maintainers should use 2FA for their accounts and
if possible provide gpg signed commits. if possible provide gpg signed commits.
https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/
https://help.github.com/articles/signing-commits-with-gpg/ https://help.github.com/articles/signing-commits-with-gpg/
@ -245,7 +254,7 @@ they served:
## Versions ## 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 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 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, pull requests on the `release/v0.9` branch and publish a `v0.9.1` tag,

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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