ctome
/
tldr
mirror of https://github.com/CrimsonTome/tldr.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

CONTRIBUTING: greatly simplify the PR instructions (#962) 

* CONTRIBUTING: greatly simplify the PR instructions

plus some wording tweaks here and there

* improve instructions to use tldrl

* brace expansion is not as common in the wild

removing it keeps the examples of unix features to a manageable/readable 3

* use actual commands in the git section

* use only one-liners on the git section

* add subsection header for commit message

* slight reword of licensing note
waldyrious/alt-syntax
Waldir Pimenta 2016-07-24 08:05:21 +01:00 committed by Leandro Ostera
parent 3da76e4150
commit 8d61f0c757
1 changed files with 43 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
CONTRIBUTING.md
View File

@ -1,20 +1,20 @@
# Contributing
Contributions 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.
Contributions 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 incorporate 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.
*Note*: when submitting a new command, don't forget to check if there's already a pull request in progress for it.
## Guidelines
Note that `tldr` is focused on concrete examples.
The basic format of a `tldr` page is a set of concrete usage 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.
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* them.
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...).
6. Focus on details specific to the command, and avoid explaining general UNIX concepts that could apply to any command (ex: relative/absolute paths, glob patterns/wildcards, special character escaping...).
The best way to be consistent is to have a look at a few existing pages :).
@ -38,14 +38,18 @@ The format of each page should match the following:
```
We actually have a linter/formatter that enforces our format.
It even automatically cleans up your pages for you! Installing it is easy:
It is run automatically on every pull request,
but you may install it to test your contributions locally before submitting them:
```
npm install
tldr tldrl
npm install tldr-lint
tldrl -f {{page.md}}
```
### Token Syntax
For other ways to use `tldrl`, such as linting an entire directory, check out (what else!)
[`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md)
### Token syntax
User-provided values should use the `{{token}}` syntax in order to allow clients
to highlight them.
@ -66,103 +70,55 @@ 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.
For submitting changes, you can use whatever workflow you're more comfortable with.
The easiest way is to just edit the page directly on the Github interface.
Check out the step-by-step instructions (with screenshots) on
[Github Help](https://help.github.com/articles/editing-files-in-another-user-s-repository/).
Detailed explanation:
Alternatively, you can do it using the command line:
1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
and configure the remotes:
- fork the repository on the github web interface
```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
```
- clone your fork locally:
2. Setup pre-commit hooks with Markdown and TLDR linter.
`git clone https://github.com/{{your_username}}/tldr.git && cd tldr`
```bash
# Assuming you have NodeJS
npm install
```
- create a feature branch, e.g. named after the command you plan to edit:
3. If you cloned a while ago, get the latest changes from upstream:
`git checkout -b {{branch_name}}`
```bash
git checkout master
git pull upstream master
```
- make your changes (edit existing files or create a new one)
4. Create a new topic branch (sometimes they are called feature branches) off
the main project development branch:
- commit the changes:
```bash
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](https://github.com/tldr-pages/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:
```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.
`git commit --all -m "{{commit_message}}"`
If page is not about a standard Unix/Linux tool, please include a link to the tool home page.
- push to your fork:
`git push`
If you are changing something non-trivial, not just adding a page for a new tool, please describe why you are doing this.
- go to the github page for your fork and click the green pull request button.
9. Verify that the automatically ran Travis CI build passed.
You can check this on your Pull Request; look for a green :heavy_check_mark: or red :x:.
Please send only related changes in the same pull request.
Typically a pull request will include changes in a single file.
10. 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.
### Commit message
11. 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.
For the commit message, use the following format:
```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
```
<command>: type of change
Examples:
- `ls: add page`
- `cat: fix typo`
- `git-push: add --force example`
- `uname: fix -a example`
## Licensing
`tldr` is under [MIT license](https://github.com/tldr-pages/tldr/blob/master/LICENSE.md).
`tldr` is licensed under the [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.
**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?