@@ -1,7 +1,7 @@
1# Contributing to Idris-Dev
1# Contributing to Idris-Dev
3The Idris Community welcomes pull requests, bug reporting, and bug squashing!
3The Idris Community welcomes pull requests, bug reporting, and bug squashing!
4−However, we cannot do it all ourself, and want to make it as easy as possible to contribute changes to get things working.
4+However, we cannot do it all ourselves, 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.
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
7## Getting Started
@@ -22,44 +22,43 @@ We do not want you wasting your time, duplicating somebody's work!
23## The Campsite Rule
23## The Campsite Rule
25−A basic rule when contributing to Idris is the **campsite rule**: leave the codebase in better condition than you found it.
25+We try to follow the **campsite rule**: leave the code base 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.
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.
28## Contributing to the default libraries.
30Idris ships with a set of packages in `libs/` that is provided as a default library.
30Idris ships with a set of packages in `libs/` that is provided as a default library.
32−+ `prelude` is the bare minimum required for any Idris program to run.
32++ `prelude` is a collection of basic definitions, automatically imported by Idris programs.
33+ `base` is tried and tested code that may be useful, and has seen active use in multiple projects.
33+ `base` is tried and tested code that may be useful, and has seen active use in multiple projects.
34−+ `contrib` is code that is experimental in design and want to test before possible inclusion in `base`.
34++ `contrib` is code that is experimental in design and that we want to test before possible inclusion in `base`.
35−+ `effects` is an implementation of algebraic effects that is packaged alongside Idris.
35++ `effects` is a library which supports effectful programming.
37−These 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.
37+These 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 yet.
38These packages offer functionality that can be built on top of when constructing Idris programs.
38These packages offer functionality that can be built on top of when constructing Idris programs.
40−When working with packages in `libs/`, it is important to realise that everything in prelude will be imported automatically, unless given the `--noprelude` option.
40+Everything in prelude will be imported automatically, unless given the `--noprelude` option.
41−Likewise, the contents of base are available with no special options.
41+The contents of base are available with no special options, but modules must be imported.
42The other two packages that ship with Idris, contrib and effects, require the use of the `-p` command-line argument to bring their contents into the include path.
42The other two packages that ship with Idris, contrib and effects, require the use of the `-p` command-line argument to bring their contents into the include path.
43−New contributions should probably be sent to contrib first, so that they can get maintained with the Idris distribution.
43+
44+New contributions should be added to the contrib package (never directly to base or prelude!).
44If they turn out to be widely applicable and useful, they may later be moved into base.
45If they turn out to be widely applicable and useful, they may later be moved into base.
46As Idris is still being developed we are open to suggestions and changes that make improvements to these default packages.
47As Idris is still being developed we are open to suggestions and changes that make improvements to these default packages.
47−Major changes to the library (or Idris itself) should ideally be discussed first through the project's official channels of communication:
48+Major changes to the library, or Idris itself, should be discussed first through the project's official channels of communication:
491. The mailing List.
501. The mailing List.
501. On our IRC Channel `#idris` on freenode, or
511. On our IRC Channel `#idris` on freenode, or
511. As a [Dragon Egg](https://github.com/idris-lang/Idris-dev/wiki/Feature-proposals).
521. As a [Dragon Egg](https://github.com/idris-lang/Idris-dev/wiki/Feature-proposals).
53−Developers 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.
54+Developers then seeking to add content to Idris's prelude and default library, should do so through a PR where more discussions and refinements can be made.
55We do not want you wasting your time nor duplicating somebody's work!
56We do not want you wasting your time nor duplicating somebody's work!
57−Of note: developers should be prepared to wait until their PR has been discussed and authorized prior to the PRs inclusion.
59## Making Changes
58## Making Changes
61Idris developers and hackers try to adhere to something similar to the [successful git branching model](http://nvie.com/posts/a-successful-git-branching-model/).
60Idris developers and hackers try to adhere to something similar to the [successful git branching model](http://nvie.com/posts/a-successful-git-branching-model/).
62−The steps are straightforward.
61+The steps are described below.
64### New contributors
63### New contributors
@@ -95,7 +94,7 @@ The remaining steps are the same for both new and existing contributors:
961. Create, and checkout onto, a topic branch on which to base you work.
951. Create, and checkout onto, a topic branch on which to base you work.
97 * This is typically the master branch.
96 * This is typically the master branch.
98− * For your own sanity, please avoid working on the `master` branch.
97+ * Please avoid working on the `master` branch.
101$ git branch fix/master/my_contrib master
100$ git branch fix/master/my_contrib master
@@ -128,7 +127,7 @@ $ git diff --check
128 single space, with blank lines in between, but conventions vary here
127 single space, with blank lines in between, but conventions vary here
1301. Make sure you have added any necessary tests for your changes.
1291. Make sure you have added any necessary tests for your changes.
131−1. Run all the tests to assure nothing else was accidentally broken.
130+1. Run all the tests to ensure nothing else was accidentally broken.
134$ make test
133$ make test
@@ -146,12 +145,12 @@ From there you will have to wait on one of the `idris-dev` committers to respond
146This response might be an accept or some changes/improvements/alternatives will be suggest.
145This response might be an accept or some changes/improvements/alternatives will be suggest.
147We do not guarantee that all requests will be accepted.
146We do not guarantee that all requests will be accepted.
149−## Increases chances of acceptance.
148+## Increasing chances of acceptance.
151To help increase the chance of your pull request being accepted:
150To help increase the chance of your pull request being accepted:
1531. Run the tests.
1521. Run the tests.
154−1. Update the documentation, the surrounding one, examples elsewhere, guides, whatever is affected by your contribution
153+1. Update the documentation, the surrounding code, examples elsewhere, guides, whatever is affected by your contribution
1551. Use appropriate code formatting for both Idris and Haskell.
1541. Use appropriate code formatting for both Idris and Haskell.
157## Additional Resources
156## Additional Resources