2014-03-04 16:39:34 +04:00
# Contributing
2016-10-02 13:08:44 +03:00
[![Gitter chat][gitter-image]][gitter-url]
[![Merged PRs][prs-merged-image]][prs-merged-url]
[![GitHub contributors][contributors-image]][contributors-url]
[![CLA assistant][cla-assistant-image]][cla-assistant-url]
[![license][license-image]][license-url]
[gitter-url]: https://gitter.im/tldr-pages/tldr
2020-06-19 01:38:47 +03:00
[gitter-image]: https://img.shields.io/badge/chat-on_gitter-deeppink
2016-10-02 13:08:44 +03:00
[prs-merged-url]: https://github.com/tldr-pages/tldr/pulls?q=is:pr+is:merged
2020-06-19 01:38:47 +03:00
[prs-merged-image]: https://img.shields.io/github/issues-pr-closed-raw/tldr-pages/tldr.svg?label=merged+PRs& color=green
2016-10-02 13:08:44 +03:00
[contributors-url]: https://github.com/tldr-pages/tldr/graphs/contributors
[contributors-image]: https://img.shields.io/github/contributors/tldr-pages/tldr.svg
[cla-assistant-url]: https://cla-assistant.io/tldr-pages/tldr
[cla-assistant-image]: https://cla-assistant.io/readme/badge/tldr-pages/tldr
[license-url]: https://github.com/tldr-pages/tldr/blob/master/LICENSE.md
2020-06-19 01:38:47 +03:00
[license-image]: https://img.shields.io/badge/license-CC_BY_4.0-blue.svg
2016-10-02 13:08:44 +03:00
2017-12-28 02:33:55 +03:00
Contributions to the tldr-pages project are [most welcome ](GOVERNANCE.md )!
All `tldr` pages are stored in Markdown right here on GitHub.
2016-07-26 12:32:22 +03:00
Just open an issue or send a pull request and we'll incorporate it as soon as possible.
2017-05-06 13:41:39 +03:00
To get started, please [sign ](https://cla-assistant.io/tldr-pages/tldr ) the
[Contributor License Agreement ](https://gist.github.com/waldyrious/e50feec13683e565769fbd58ce503d4e ).
2014-03-04 16:39:34 +04:00
2016-07-24 10:05:21 +03:00
*Note*: when submitting a new command, don't forget to check if there's already a pull request in progress for it.
2015-04-12 22:54:27 +03:00
2014-03-04 16:39:34 +04:00
## Guidelines
2016-07-24 10:05:21 +03:00
The basic format of a `tldr` page is a set of concrete usage examples.
2016-01-07 22:53:19 +03:00
Here are a few guidelines to get started:
2014-03-04 16:39:34 +04:00
2016-11-19 20:16:19 +03:00
1. Try to keep pages at around 5 examples. Pages can be longer if needed, but don't exceed 8 examples.
Remember, it's OK if the page doesn't cover everything; that's what `man` is for.
2016-10-14 21:19:37 +03:00
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.
2016-07-26 12:32:22 +03:00
3. Try to incorporate the spelled-out version of single-letter options in the example's description.
The goal is to allow people to *understand* the syntax of the commands, not just *memorize* it.
2016-10-02 13:03:37 +03:00
4. Introduce options gradually, starting with the simplest command invocations,
and using more complex examples progressively.
2016-11-20 14:35:49 +03:00
5. Focus on details specific to the command, and avoid explaining general UNIX concepts that could apply to any command
2016-07-26 12:32:22 +03:00
(ex: relative/absolute paths, glob patterns/wildcards, special character escaping...).
2014-03-04 16:39:34 +04:00
2017-10-28 13:24:15 +03:00
These are all guidelines, not strict rules.
2020-01-23 03:09:12 +03:00
Use proper judgement, keeping simplicity and user-friendliness as the top priorities.
2017-10-28 13:24:15 +03:00
When in doubt, have a look at a few existing pages :).
2014-03-04 16:39:34 +04:00
## Markdown format
2017-10-28 13:24:15 +03:00
As a quick reference, the format of each page should match the following template:
2014-03-04 16:39:34 +04:00
```
# command-name
2016-01-07 22:53:19 +03:00
> Short, snappy description.
2016-01-08 05:01:59 +03:00
> Preferably one line; two are acceptable if necessary.
2014-03-04 16:39:34 +04:00
2016-01-07 22:53:19 +03:00
- Example description:
2014-03-04 16:39:34 +04:00
2015-08-25 03:16:26 +03:00
`command -opt1 -opt2 -arg1 {{arg_value}}`
2014-03-04 16:39:34 +04:00
2016-01-07 22:53:19 +03:00
- Example description:
2014-03-04 16:39:34 +04:00
2015-08-25 03:16:26 +03:00
`command -opt1 -opt2`
2014-03-04 16:39:34 +04:00
```
2017-10-28 13:24:15 +03:00
For more detailed page formatting guidelines,
2017-11-29 09:11:28 +03:00
refer to the [style guide ](contributing-guides/style-guide.md ).
2016-07-26 12:32:22 +03:00
2020-05-10 02:10:23 +03:00
## Subcommands
Many programs use subcommands for separating functionality, which may require their own separate pages.
For instance, `git commit` has its own page, as well as `git push` and many others.
To create a page for a subcommand, the program and subcommand need to be separated with a dash (`-`), so `git-commit.md` is shown when calling `tldr git commit` .
You should always add a base page (e.g. `git` ) that describes the program and basic switches like `--version` or `help` .
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 )
2019-01-11 22:37:47 +03:00
## Translations
2019-01-12 12:17:13 +03:00
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.
2019-01-11 22:37:47 +03:00
2019-08-23 20:12:48 +03:00
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:
2019-01-11 22:37:47 +03:00
- `<language>` is the shortest [ISO 639 ](https://en.wikipedia.org/wiki/ISO_639 ) language code for the chosen language (see [here ](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes ) for a complete list).
2019-08-23 20:12:48 +03:00
- `<country>` is the two-letter [ISO 3166-1 ](https://en.wikipedia.org/wiki/ISO_3166-1 ) country code for the chosen region (see [here ](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements ) for a complete list).
2019-01-11 22:37:47 +03:00
2019-08-23 20:12:48 +03:00
The `<country>` code is optional and should only be added when it is needed. In other words, only when there is a valid reason to distinguish between a language (`ll`) and its regional dialects (`ll_CC1`, `ll_CC2` , etc.). As an example, both `fr_FR` and `fr_BE` should fall under the same `pages.fr` directory, since there virtually is no difference in writing between standard French and Belgian French.
2019-01-11 22:37:47 +03:00
2019-08-26 11:43:23 +03:00
Some examples of valid locale tags:
2019-01-12 12:17:13 +03:00
- French: `fr` .
- Chinese: `zh` .
2019-08-23 20:12:48 +03:00
- Chinese (Singapore): `zh_SG` .
- Portuguese (Brazil): `pt_BR` .
2019-01-11 22:37:47 +03:00
2019-01-11 23:18:26 +03:00
### Default language for newly added pages
2019-01-12 12:17:13 +03:00
The default language used for pages is English (US). Pages written in English are stored in the default `pages` directory (notice the absence of a specific language tag). Although not strictly required, if you'd like to add a new page in a different language, please consider creating the English page too.
2019-01-11 23:18:26 +03:00
2015-12-29 03:36:49 +03:00
## Submitting a pull request
2019-12-08 01:36:53 +03:00
The easiest way to submit a change is to just edit the page directly on the GitHub interface.
2016-07-24 10:05:21 +03:00
Check out the step-by-step instructions (with screenshots) on
2019-12-08 01:36:53 +03:00
[GitHub Help ](https://help.github.com/articles/editing-files-in-another-user-s-repository/ ).
2015-12-29 03:36:49 +03:00
2017-11-27 21:43:52 +03:00
Alternatively, you can do most of the process
[using git on the command line ](contributing-guides/git-terminal.md ).
2016-01-25 01:37:37 +03:00
2016-07-24 10:05:21 +03:00
### Commit message
2015-12-29 03:36:49 +03:00
2016-07-24 10:05:21 +03:00
For the commit message, use the following format:
2016-01-03 13:01:16 +03:00
2016-07-24 10:05:21 +03:00
< command > : type of change
2015-12-29 03:36:49 +03:00
2016-07-24 10:05:21 +03:00
Examples:
2018-11-14 02:39:53 +03:00
- For a new page addition: `ls: add page`
- For a page edit: `cat: fix typo` , `git-push: add --force example`
- For a new translation of an existing page: `cp: add Tamil translation`
- For related changes to several pages: `grep, find, locate: synchronize format of wildcards`
2015-12-29 03:36:49 +03:00
## Licensing
2020-05-11 02:23:54 +03:00
This repository is licensed under the [Creative Commons Attribution 4.0 International License ](LICENSE.md ).
The contents of the `scripts/` directory are licensed under the [MIT license ](LICENSE.md ).
2014-03-04 16:39:34 +04:00
2016-10-02 13:03:37 +03:00
Any contributions to this project are governed by the
[Contributor License Agreement ](https://cla-assistant.io/tldr-pages/tldr ).