From f91917f3e4064dbc93e144efd6162577f705d6b7 Mon Sep 17 00:00:00 2001 From: "K.B.Dharun Krishna" Date: Thu, 28 Dec 2023 22:01:43 +0530 Subject: [PATCH] cleanup: update contributing guide (#11861) Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com> --- CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0052505686..2d05eb5094 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ The basic format of a `tldr` page is a set of concrete usage examples. Here are a few guidelines to get started: -1. Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate, but don't exceed the maximum of eight examples. +1. Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate but don't exceed the maximum of eight examples. Remember, it's OK if the page doesn't cover everything; that's what `man` is for. 2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness. For example, commands that require `sudo` should include it directly in the examples. @@ -71,7 +71,7 @@ As a quick reference, the format of each page should match the following templat For page descriptions, you can additionally use ``See also: `command`.`` and [subcommand reference](#subcommands). > [!NOTE] -> While we suggest only two lines for the page description, it is acceptable to have more than two lines if it necessary to add additional information (i.e. [`pacman`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/pacman.md)). +> While we suggest only two lines for the page description, it is acceptable to have more than two lines if it is necessary to add additional information (i.e. [`pacman`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/pacman.md)). To see some examples of preexisting pages, you can look at: @@ -98,21 +98,44 @@ To create a page for a subcommand, the program and subcommand need to be separat You should always add a base page (e.g. `git`) that describes the program and basic switches like `--version` or `--help`. -To let others know about the subcommand, add a note saying ``Some subcommands such as `example command` have their own usage documentation`` to the base page. +### Referencing subcommands + +The following methods can be used to reference subcommands: + +- You can add a note saying ``Some subcommands such as `example command` have their own usage documentation`` to the main page. (See the [subcommand reference](/contributing-guides/translation-templates/subcommand-mention.md) page for translation templates.) +- You can use ``See also: `command1`, `command2`.`` template to reference similar commands, aliases and subcommands. +- Alternatively, the whole page can be converted to reference the main subcommands. + +For example: + +```md +# command + +> Short, snappy description. +> Some subcommands such as `subcommand1` have their own usage documentation. +> More information: . + +- View documentation for creating something: + +`tldr command-subcommand1` + +- View documentation for managing something: + +`tldr command-subcommand2` +``` See these examples for reference: - [git](pages/common/git.md) -- [git-commit](pages/common/git-commit.md) -- [aws](pages/common/aws.md) -- [aws-s3](pages/common/aws-s3.md) +- [distrobox-create](pages/linux/distrobox-create.md) +- [nmcli](pages/linux/nmcli.md) ## Translations Translation of pages can be done by simply creating the corresponding page within the appropriate language-specific directory, creating that as well if it does not already exist. > [!IMPORTANT] -> Translations of pages should be done based on the English (US) page in the `pages` directory. If the English pages doesn't exist for the command, it should be added first in a PR before creating a translation. +> Translations of pages should be done based on the English (US) page in the `pages` directory. If the English pages don't exist for the command, it should be added first in a PR before creating a translation. Language specific directories must follow the pattern `pages.`, where `` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `[_]`, where: @@ -124,6 +147,9 @@ The `` code is optional and should only be added when it is needed. In > [!IMPORTANT] > When adding a new language to `tldr`, it is suggested to add it to the [translation templates](contributing-guides/translation-templates) along with any page additions. +> [!TIP] +> When fixing errors in an existing translation, it is suggested to update the page to match the latest version of the English page. + To see the current progress of all translations, you can visit , which provides a dynamically updated table of all pages and their translations. Some examples of valid locale tags: @@ -137,7 +163,7 @@ A list of translated templates for alias pages can be found [here](contributing- It is acceptable for several pages to get translated in one pull request. -For more information about language specific rules, refer to the [style guide](contributing-guides/style-guide.md#language-specific-rules). +For more information about language-specific rules, refer to the [style guide](contributing-guides/style-guide.md#language-specific-rules). ## Inclusive language @@ -165,7 +191,7 @@ tldr-lint {{path/to/page.md}} Now, you are ready to submit a pull request! > [!TIP] -> Additionally, inside the `tldr` directory you can install the dependencies using `npm install` command and now when you commit your changes, the tests will run automatically via the pre-commit hook. +> Additionally, inside the `tldr` directory you can install the dependencies using the `npm install` command and now when you commit your changes, the tests will run automatically via the pre-commit hook. (To skip the pre-commit hook and immediately commit your changes use the `git commit --no-verify` command). ### Submitting changes @@ -188,7 +214,7 @@ To commit a suggestion to your pull request, click on `Commit suggestion`: ![Commit suggestion button in Github](./images/commit-suggestion-button.png) -If you want to commit multiple suggestions, go to the "Files changed" tab and batch all suggestions. Now, click `Commit suggestions` button and enter a commit message to create a single commit. +If you want to commit multiple suggestions, go to the "Files changed" tab and batch all suggestions. Now, click the `Commit suggestions` button and enter a commit message to create a single commit. ### Commit message @@ -206,10 +232,16 @@ Where `{{command}}` is the name of the command being modified, and `type of chan - For multiple subcommand page additions: `git-{add, push, ...}: add page` - For modifying multiple pages in a language: `pages./*: update pages` ---- - For other cases, its suggested to follow as much as possible. +## Name collisions + +When there are multiple commands sharing the same name, the existing page of the command and the new command can be renamed to `command.1` and so on following a numbering scheme or based on the programming language i.e. `command.js`. The base page can be updated to reference the newly renamed/created pages by following [this subcommand reference format](#subcommands). + +See the following page for reference: + +- [just](pages/common/just.md) + ## Licensing This repository is licensed under the [Creative Commons Attribution 4.0 International License](LICENSE.md).