Skip to content

Latest commit

 

History

History
168 lines (115 loc) · 5.92 KB

CONTRIBUTING.md

File metadata and controls

168 lines (115 loc) · 5.92 KB
Raw

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 are 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, snappy description.
> Preferably one line; two are acceptable if necessary.

- Example description:

`command -opt1 -opt2 -arg1 {{arg_value}}`

- Example description:

`command -opt1 -opt2`

We actually have a linter/formatter that enforces our format. It even automatically cleans up your pages for you! Installing it is easy:

npm install
tldr tldrl

Token Syntax

User-provided values should use the {{token}} syntax in order to allow clients to highlight them.

Some examples:

  • tar cf {{file}}
  • ln -s {{path/to/original/file}} {{path/to/link}}
  • mysql {{database_name}}
  • unrar x {{compressed.rar}}

In short, make it as intuitive as possible for the user to figure out how to use the command and fill it in with values. Stick to snake_case where possible. In some situations a command works with typical file extensions (like the unrar example above); you are encouraged to add these for demonstration.

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, clone, npm install, feature branch, commit, push, pull request, check Travis.

Detailed explanation:

  1. Fork the project, clone your fork, and configure the remotes:

    # 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 pre-commit hooks with Markdown and TLDR linter.

    # Assuming you have NodeJS
npm install

  3. If you cloned a while ago, get the latest changes from upstream:

    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:

    git checkout -b <topic-branch-name>

  5. Run npm test to check that your page(s) are correct. Try to run the commands you are describing to ensure the syntax is correct.

    You can use the formatting features of tldr-lint (installed through npm install) to automatically fix any mistakes you may have missed. Try tldr tldrl for a quick how-to.

  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:

    git push origin <topic-branch-name>

  8. Open a Pull Request 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. Verify that the automatically ran Travis CI build passed. You can check this on your Pull Request; look for a green ✔️ or red ❌.

  10. Use Git's 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:

In most cases it is better to squash commits before submitting a pull request.

  1. 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.
# 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.

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 and periodically updates straight from this repo?