git.iko.soy/Idris-dev
on f572cd0 help sign in
Idris-dev/docs/CONTRIBUTING.md
132 lines 4.5 kB history raw
1# Contributing Guidelines
4The Idris Community welcomes pull requests, bug reporting, and bug squashing!
5However, we cannot do it all ourself, and want to make it as easy as possible to contribute changes to get things working.
6Here are a few guidelines that we would like contributors to follow so that we can have a chance of keeping on top of things.
8## Getting Started
101. Make sure you are familiar with [Git](http://git-scm.com/book).
111. Make sure you have a [GitHub account](https://github.com/signup/free).
121. Make sure you are familiar with: [Sphinx](http://www.sphinx-doc.org).
14## Issue Reporting
16Before you report an issue, or wish to add more content please try and check to see if there are existing [issues](https://github.com/jfdm/idris-manual/issues) and [pull requests](https://github.com/jfdm/idris-manual/pulls).
17We do not want you wasting your time, duplicating somebody's work!
19Of note: developers should be prepared to wait until their PR has been discussed and authorized prior to the PRs inclusion.
21## The Campsite Rule
23A basic rule when contributing to this project is the **campsite rule**: leave the project in better condition than you found it.
24Please clean up any messes that you find, and don't leave behind new messes for the next contributor.
26## Making Changes
28Idris developers and hackers try to adhere to something similar to the [successful git branching model](http://nvie.com/posts/a-successful-git-branching-model/).
29The steps are straightforward.
31Please consult STYLE-GUIDE.md for information on writing styles.
33### New contributors
35For those new to the project:
371. Fork our [main development repository](https://github.com/jfdm/idris-manual) `idris-manual` on github e.g.
382. Clone your fork to your local machine:
40```
41$ git clone git@github.com/<your github user name>/idris-manual.git
42```
443. Add `jfdm/idris-manual` as a remote upstream
46```
47$ git remote add upstream git@github.com:jfdm/idris-manual.git
48```
50### Existing Contributors
52For those already contributing to the project:
541. Ensure your existing clone is up-to-date with current `HEAD` e.g.
56```
57$ git fetch upstream
58$ git merge upstream/master
59```
61### Remaining Steps
63The remaining steps are the same for both new and existing contributors:
651. Create, and checkout onto, a topic branch on which to base you work.
66* This is typically the master branch.
67* For your own sanity, please avoid working on the `master` branch.
69```
70$ git branch fix/master/my_contrib master
71$ git checkout fix/master/my_contrib
72```
741. Make commits of logical units.
751. Check for unnecessary whitespace with
77```
78$ git diff --check
79```
811. Make sure your commit messages are along the lines of:
83Short (50 chars or less) summary of changes
85More detailed explanatory text, if necessary. Wrap it to about 72
86characters or so. In some contexts, the first line is treated as the
87subject of an email and the rest of the text as the body. The blank
88line separating the summary from the body is critical (unless you omit
89the body entirely); tools like rebase can get confused if you run the
90two together.
92Further paragraphs come after blank lines.
94- Bullet points are okay, too
96- Typically a hyphen or asterisk is used for the bullet, preceded by a
97single space, with blank lines in between, but conventions vary here
991. Make sure you have added any necessary tests for your changes.
1001. Run all the tests to assure nothing else was accidentally broken.
102```
103$ make test
104```
1061. Push your changes to a topic branch in your fork of the repository.
108```
109$ git push origin fix/master/my_contrib
110```
1121. Go to GitHub and submit a pull request to `idris-manual`
114From there you will have to wait on one of the `idris-manual` committers to respond to the request.
115This response might be an accept or some changes/improvements/alternatives will be suggest.
116We do not guarantee that all requests will be accepted.
118## Increases chances of acceptance.
120To help increase the chance of your pull request being accepted:
1221. Spell and Grammar check your work.
1231. Ensure that the documentation will compile for all outputs used.
1241. Use appropriate formatting for reST.
126## Additional Resources
128* [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
129* [General GitHub Documentation](https://help.github.com/).
132Adapted from the most excellent contributing files from the [Puppet project](https://github.com/puppetlabs/puppet) and [Factroy Girl Rails](https://github.com/thoughtbot/factory_girl_rails/blob/master/CONTRIBUTING.md)