mirror of https://github.com/CrimsonTome/tldr.git
140 lines
4.9 KiB
Markdown
140 lines
4.9 KiB
Markdown
# Contributing
|
|
|
|
Contribution are most welcome! All `tldr` pages are stored in Markdown right here on GitHub. Just open an issue or send a pull request and we'll merge it as soon as possible.
|
|
|
|
*Note*: when submitting a new command, don't forget to check if there's already a pull request in progress.
|
|
|
|
## Guidelines
|
|
|
|
Note that `tldr` is focused on concrete examples.
|
|
Here's a few guidelines to get started:
|
|
|
|
1. Focus on the 5 or 6 most common usages. 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.
|
|
3. Try to incorporate the spelled-out version of single-letter options in the example's description.
|
|
4. Introduce options gradually, starting with the simplest commands and using more complex examples progressively.
|
|
5. Use short but descriptive values for the tokens, ex. `{{source_file}}` or `{{wallet.txt}}`.
|
|
6. Be specific: avoid explaining general UNIX concepts that could apply to any command (ex: relative/absolute paths, brace expansion, character escaping...)
|
|
|
|
The best way to be consistent is to have a look at a few existing pages :)
|
|
|
|
## Markdown format
|
|
|
|
The format of each page should match the following:
|
|
|
|
```
|
|
# command-name
|
|
|
|
> Short description
|
|
> Max 1 or 2 lines
|
|
|
|
- example description
|
|
|
|
`command -opt1 -opt2 -arg1 {{arg_value}}`
|
|
|
|
- example description
|
|
|
|
`command -opt1 -opt2`
|
|
```
|
|
|
|
User-provided values should use the `{{token}}` syntax, to allow clients to highlight them. For example: `tar cf {{file}}`
|
|
|
|
One of the reasons for this format is that it's well suited for command-line clients that need to extract a single description/example.
|
|
|
|
## Submitting a pull request
|
|
|
|
TL;DR: fork, `make setup`, feature branch, commit, push, pull request.
|
|
|
|
Detailed explanation:
|
|
|
|
1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
|
|
and configure the remotes:
|
|
|
|
```bash
|
|
# Clone your fork of the repo into the current directory
|
|
git clone https://github.com/<your-username>/tldr
|
|
# Navigate to the newly cloned directory
|
|
cd tldr
|
|
# Assign the original repo to a remote called "upstream"
|
|
git remote add upstream https://github.com/tldr-pages/tldr
|
|
```
|
|
|
|
2. Setup Ruby, Rubygems, bundler, Git pre-commit hooks with Markdown linter.
|
|
|
|
```bash
|
|
# Assuming Ruby is set up
|
|
# Install bundler Ruby gem
|
|
gem install bundler
|
|
make setup
|
|
```
|
|
|
|
3. If you cloned a while ago, get the latest changes from upstream:
|
|
|
|
```bash
|
|
git checkout master
|
|
git pull upstream master
|
|
```
|
|
|
|
4. Create a new topic branch (sometimes they are called feature branches) off
|
|
the main project development branch:
|
|
|
|
```bash
|
|
git checkout -b <topic-branch-name>
|
|
```
|
|
|
|
5. Run `make lint` to check that your page(s) are correct. Try to run the commands you are describing to ensure the syntax is correct.
|
|
|
|
6. Please use the following commit message format:
|
|
`<command>: type of change`.
|
|
|
|
Examples:
|
|
|
|
- `ls: add page`
|
|
- `cat: fix typo`
|
|
- `git-push: add --force example`
|
|
- `uname: fix -a example`
|
|
|
|
7. Push your topic branch up to your fork:
|
|
|
|
```bash
|
|
git push origin <topic-branch-name>
|
|
```
|
|
|
|
8. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
|
|
with a clear title and description.
|
|
|
|
If page is not about a standard Unix/Linux tool, please include a link to the tool home page.
|
|
|
|
If you are changing something non-trivial, not just adding a page for a new tool, please describe why you are doing this.
|
|
|
|
9. Use Git's
|
|
[interactive rebase](https://help.github.com/articles/interactive-rebase)
|
|
feature to tidy up your commits before making them public.
|
|
|
|
If you are not familiar with `git rebase`, it might be helpful to check out these video tutorials:
|
|
- [Git Rebase: squash last commits](https://www.youtube.com/watch?v=qh9KtjfjzCU)
|
|
- [Learning Git Tutorial: Interactive Rebasing](https://www.youtube.com/watch?v=NW46XmvJh5Q)
|
|
|
|
In most cases it is better to squash commits before submitting a pull request.
|
|
|
|
10. If you do not want to do a rebasing, you can overwrite your last commit in pull request, while you have only a single commit. You can achieve this with `git commit --amend` command.
|
|
|
|
```bash
|
|
# When you are on topic branch of your pull request
|
|
# Fix your files
|
|
|
|
git add . # Register edited files
|
|
git commit --amend # Do amended commit
|
|
git push --force # Overwrite your branch
|
|
```
|
|
|
|
|
|
## Licensing
|
|
|
|
`tldr` is under [MIT license](https://github.com/tldr-pages/tldr/blob/master/LICENSE.md).
|
|
|
|
**IMPORTANT**: By submitting a patch, you agree to license your work under the
|
|
same license as that used by the project.
|
|
|
|
You're free to modify or redistribute the content. That being said, but why not contribute over here? :) Say if you wanted to have `tldr` pages in `groff` format, why not have a client that uses [pandoc](http://johnmacfarlane.net/pandoc/) and periodically updates straight from this repo?
|