mirror of
https://github.com/tldr-pages/tldr.git
synced 2024-08-16 23:40:43 +03:00
cleanup: update contributing guide (#11861)
Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>
This commit is contained in:
parent
161f26d045
commit
f91917f3e4
@ -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: <https://url-to-upstream.tld>.
|
||||
|
||||
- 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.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>[_<country>]`, where:
|
||||
|
||||
@ -124,6 +147,9 @@ The `<country>` 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 <https://lukwebsforge.github.io/tldri18n/>, 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.<locale>/*: update pages`
|
||||
|
||||
---
|
||||
|
||||
For other cases, its suggested to follow <https://www.conventionalcommits.org/> 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).
|
||||
|
Loading…
Reference in New Issue
Block a user