Improve Contributing Guidelines:

- mention feature branches
- have detailed workflow to work with pull requests
- move it to the bottom
- add link to license
- some minor fixes
waldyrious/alt-syntax
Igor Shubovych 2015-12-29 02:36:49 +02:00
parent 46c91180fc
commit 76f94dfac2
1 changed files with 78 additions and 10 deletions

View File

@ -1,15 +1,8 @@
# Contributing
- Your favourite command isn't covered?
- You can think of more examples?
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.*
## Setup
When setting up a brand new fork, run `make setup` to install the git pre-commit hook that will check errors in your changes with Markdown linter.
*Note*: when submitting a new command, don't forget to check if there's already a pull request in progress.
## Guidelines
@ -48,8 +41,83 @@ User-provided values should use the `{{token}}` syntax, to allow clients to high
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
**Footnote:** tldr is under MIT license.
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.
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.
9. Use Git's
[interactive rebase](https://help.github.com/articles/interactive-rebase)
feature to tidy up your commits before making them public.
In most cases it is better to squash commits before submitting a pull request.
10. If you are asked to amend your changes before they can be merged in, please
use `git commit --amend` and force push to your remote feature branch.
You may also be asked to squash commits.
## 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?