git.iko.soy/Idris-dev
on 7d42ba2 help sign in
Idris-dev/CONTRIBUTING.md
158 lines 6.9 kB history raw
1# Contributing to Idris-Dev
3The Idris Community welcomes pull requests, bug reporting, and bug squashing!
4However, we cannot do it all ourself, and want to make it as easy as possible to contribute changes to get things working.
5Here are a few guidelines that we would like contributors to follow so that we can have a chance of keeping on top of things.
7## Getting Started
91. Make sure you are familiar with [Git](http://git-scm.com/book).
101. Make sure you have a [GitHub account](https://github.com/signup/free).
111. Make sure you are familiar with: [Idris](http://eb.host.cs.st-andrews.ac.uk/writings/idris-tutorial.pdf).
121. Make sure you can install `Idris`:
13 * [Mac OS X](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-OS-X-using-Homebrew)
14 * [Ubuntu](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-Ubuntu)
15 * [Debian](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-Debian)
16 * [Windows](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-Windows)
18## Issue Reporting
20Before you report an issue, or wish to add cool functionality please try and check to see if there are existing [issues](https://github.com/idris-lang/Idris-dev/issues) and [pull requests](https://github.com/idris-lang/Idris-dev/pulls).
21We do not want you wasting your time, duplicating somebody's work!
23## The Campsite Rule
25A basic rule when contributing to Idris is the **campsite rule**: leave the codebase in better condition than you found it.
26Please clean up any messes that you find, and don't leave behind new messes for the next contributor.
28## Contributing to the default libraries.
30`Idris` ships with a set of packages in `libs/` that is provided as a default library.
31These packages should not be seen as the *standard* as when working with dependent types we do not necessarily know how best to work with dependent types.
32These packages offer functionality that can be built on top of when constructing `Idris` programs.
34One major point to make is that everything in prelude will be imported automatically, unless given
35the `--noprelude` option.
36A central idea within the `Idris` Community is that what counts as `Idris` is: **the compiler plus the Standard Prelude**.
37Other libraries (base, effects, etc) are still part of the distribution, but not necessarily standard.
39As `Idris` is still being developed we are open to suggestions and changes that make improvements to these default packages.
40Major changes to the library (or `Idris` itself) should ideally be discussed first through the projects official channels of communication i.e. the mailing list, github wiki, or IRC, or as a [Dragon Egg](https://github.com/idris-lang/Idris-dev/wiki/Feature-proposals).
41Developers then seeking to add content to `Idris`s prelude and default library, should do so through a PR where more discussion's and refinements can be made.
43We do not want you wasting your time nor duplicating somebody's work!
45Of note: developers should be prepared to wait until their PR has been discussed and authorized prior to the PRs inclusion.
47## Making Changes
49Idris developers and hackers try to adhere to something similar to the [successful git branching model](http://nvie.com/posts/a-successful-git-branching-model/).
50The steps are straightforward.
52### New contributors
54For those new to the project:
561. Fork our [main development repository](https://github.com/idris-lang/Idris-dev) `idris-dev` on github e.g.
572. Clone your fork to your local machine:
59```
60$ git clone git@github.com/<your github user name>/Idris-dev.git
61```
633. Add `idris-lang/Idris-dev` as a remote upstream
65```
66$ git remote add upstream git@github.com:idris-lang/Idris-dev.git
67```
69### Existing Contributors
71For those already contributing to the project:
731. Ensure your existing clone is up-to-date with current `HEAD` e.g.
75```
76$ git fetch upstream
77$ git merge upstream/master
78```
80### Remaining Steps
82The remaining steps are the same for both new and existing contributors:
841. Create, and checkout onto, a topic branch on which to base you work.
85 * This is typically the master branch.
86 * For your own sanity, please avoid working on the `master` branch.
88```
89$ git branch fix/master/my_contrib master
90$ git checkout fix/master/my_contrib
91```
931. Make commits of logical units.
941. Check for unnecessary whitespace with
96```
97$ git diff --check
98```
1001. Make sure your commit messages are along the lines of:
102 Short (50 chars or less) summary of changes
104 More detailed explanatory text, if necessary. Wrap it to about 72
105 characters or so. In some contexts, the first line is treated as the
106 subject of an email and the rest of the text as the body. The blank
107 line separating the summary from the body is critical (unless you omit
108 the body entirely); tools like rebase can get confused if you run the
109 two together.
111 Further paragraphs come after blank lines.
113 - Bullet points are okay, too
115 - Typically a hyphen or asterisk is used for the bullet, preceded by a
116 single space, with blank lines in between, but conventions vary here
1181. Make sure you have added any necessary tests for your changes.
1191. Run all the tests to assure nothing else was accidentally broken.
121```
122$ make test
123```
1251. Push your changes to a topic branch in your fork of the repository.
127```
128$ git push origin fix/master/my_contrib
129```
1311. Go to GitHub and submit a pull request to `idris-dev`
133From there you will have to wait on one of the `idris-dev` committers to respond to the request.
134This response might be an accept or some changes/improvements/alternatives will be suggest.
135We do not guarantee that all requests will be accepted.
137## Increases chances of acceptance.
139To help increase the chance of your pull request being accepted:
1411. Run the tests.
1421. Update the documentation, the surrounding one, examples elsewhere, guides, whatever is affected by your contribution
1431. Use appropriate code formatting for both `Idris` and `Haskell`.
145## Additional Resources
147* [Idris Wiki](https://github.com/idris-lang/Idris-dev/wiki);
148* [Zen Of Idris](https://github.com/idris-lang/Idris-dev/wiki/The-Zen-of-Idris);
149* Idris FAQs: [Official](http://www.idris-lang.org/documentation/faq/); [Unofficial](https://github.com/idris-lang/Idris-dev/wiki/Unofficial-FAQ);
150* [Idris Manual](https://github.com/idris-lang/Idris-dev/wiki/Manual);
151* [Idris Tutorial](http://eb.host.cs.st-andrews.ac.uk/writings/idris-tutorial.pdf);
152* [Idris News](http://www.idris-lang.org/news/);
153* [other Idris docs](http://www.idris-lang.org/documentation/).
154* [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
155* [General GitHub Documentation](https://help.github.com/).
158Adapted 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)