2013-12-10 21:11:21 +04:00
# Contributing to Idris-Dev
The Idris Community welcomes pull requests, bug reporting, and bug squashing!
2015-03-29 19:10:03 +03:00
However, we cannot do it all ourselves, and want to make it as easy as possible to contribute changes to get things working.
2013-12-10 21:11:21 +04:00
Here are a few guidelines that we would like contributors to follow so that we can have a chance of keeping on top of things.
## Getting Started
2019-12-19 16:24:06 +03:00
1. Make sure you are familiar with [Git ](https://git-scm.com/book ).
2013-12-10 21:11:21 +04:00
1. Make sure you have a [GitHub account ](https://github.com/signup/free ).
2019-12-19 16:24:06 +03:00
1. Make sure you are familiar with: [Idris ](https://eb.host.cs.st-andrews.ac.uk/writings/idris-tutorial.pdf ).
2015-03-19 23:02:37 +03:00
1. Make sure you can install Idris:
2013-12-10 21:11:21 +04:00
* [Mac OS X ](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-OS-X-using-Homebrew )
* [Ubuntu ](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-Ubuntu )
* [Debian ](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-Debian )
* [Windows ](https://github.com/idris-lang/Idris-dev/wiki/Idris-on-Windows )
2014-10-15 17:09:53 +04:00
## Issue Reporting
2013-12-10 21:11:21 +04:00
Before 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 ).
We do not want you wasting your time, duplicating somebody's work!
2017-08-05 16:54:22 +03:00
### Template
Try as closely as possible to describe the issue, ensuring that it has sections that match the following headings:
> \# Steps to Reproduce
>
> \# Expected Behavior
>
> \# Observed Behavior
>
>
In addition, please attach complete source files that exhibit the issue to quoting from them in the issue.
### Feature Requests
2017-08-05 17:02:10 +03:00
We would be delighted to receive feature requests only if they are feasible to implement and the author is willing to implement the suggested features themself. The current Idris developer team consists mostly of volunteers, and so it is unfortunately hard to accommodate implementing nice-to-have ideas that are not essential for core language development.
2017-08-05 16:54:22 +03:00
2013-12-18 23:02:33 +04:00
## The Campsite Rule
2015-03-29 19:10:03 +03:00
We try to follow the **campsite rule** : leave the code base in better condition than you found it.
2013-12-18 23:02:33 +04:00
Please clean up any messes that you find, and don't leave behind new messes for the next contributor.
2014-10-15 17:09:53 +04:00
## Contributing to the default libraries.
2015-03-19 23:02:37 +03:00
Idris ships with a set of packages in `libs/` that is provided as a default library.
2015-03-23 12:55:14 +03:00
2015-03-29 19:10:03 +03:00
+ `prelude` is a collection of basic definitions, automatically imported by Idris programs.
2015-03-23 12:55:14 +03:00
+ `base` is tried and tested code that may be useful, and has seen active use in multiple projects.
2015-03-29 19:10:03 +03:00
+ `contrib` is code that is experimental in design and that we want to test before possible inclusion in `base` .
+ `effects` is a library which supports effectful programming.
2015-03-23 12:55:14 +03:00
2015-03-29 19:10:03 +03:00
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.
2015-03-19 23:02:37 +03:00
These packages offer functionality that can be built on top of when constructing Idris programs.
2014-10-15 17:09:53 +04:00
2015-03-29 19:10:03 +03:00
Everything in prelude will be imported automatically, unless given the `--noprelude` option.
The contents of base are available with no special options, but modules must be imported.
2015-03-23 12:55:14 +03:00
The 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.
2015-03-29 19:10:03 +03:00
New contributions should be added to the contrib package (never directly to base or prelude!).
2015-03-19 23:08:03 +03:00
If they turn out to be widely applicable and useful, they may later be moved into base.
2014-10-15 17:09:53 +04:00
2015-03-19 23:02:37 +03:00
As Idris is still being developed we are open to suggestions and changes that make improvements to these default packages.
2015-03-29 19:10:03 +03:00
Major changes to the library, or Idris itself, should be discussed first through the project's official channels of communication:
2015-03-23 12:55:14 +03:00
1. The mailing List.
1. On our IRC Channel `#idris` on freenode, or
2016-06-20 00:07:47 +03:00
1. As an RFC in the issue tracker
2015-03-23 12:55:14 +03:00
2015-03-29 19:10:03 +03:00
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.
2014-10-15 17:09:53 +04:00
We do not want you wasting your time nor duplicating somebody's work!
2013-12-10 21:11:21 +04:00
## Making Changes
2019-12-19 16:24:06 +03:00
Idris developers and hackers try to adhere to something similar to the [successful git branching model ](https://nvie.com/posts/a-successful-git-branching-model/ ).
2015-03-29 19:10:03 +03:00
The steps are described below.
2013-12-10 21:11:21 +04:00
2014-01-22 16:10:23 +04:00
### New contributors
2013-12-10 21:11:21 +04:00
For those new to the project:
2014-01-22 16:10:23 +04:00
1. Fork our [main development repository ](https://github.com/idris-lang/Idris-dev ) `idris-dev` on github e.g.
2. Clone your fork to your local machine:
```
2018-11-06 13:59:52 +03:00
$ git clone git@github.com:< your github user name > /Idris-dev.git
2014-01-22 16:10:23 +04:00
```
3. Add `idris-lang/Idris-dev` as a remote upstream
2013-12-10 21:11:21 +04:00
2014-01-22 16:10:23 +04:00
```
$ git remote add upstream git@github.com:idris-lang/Idris-dev.git
```
### Existing Contributors
2013-12-10 21:11:21 +04:00
For those already contributing to the project:
2014-01-22 16:10:23 +04:00
1. Ensure your existing clone is up-to-date with current `HEAD` e.g.
```
$ git fetch upstream
$ git merge upstream/master
```
2013-12-10 21:11:21 +04:00
2014-01-22 16:10:23 +04:00
### Remaining Steps
2013-12-10 21:11:21 +04:00
2014-01-22 16:10:23 +04:00
The remaining steps are the same for both new and existing contributors:
2013-12-10 21:11:21 +04:00
1. Create, and checkout onto, a topic branch on which to base you work.
* This is typically the master branch.
2015-03-29 19:10:03 +03:00
* Please avoid working on the `master` branch.
2013-12-10 21:11:21 +04:00
2014-01-22 16:10:23 +04:00
```
$ git branch fix/master/my_contrib master
$ git checkout fix/master/my_contrib
```
2013-12-10 21:11:21 +04:00
1. Make commits of logical units.
1. Check for unnecessary whitespace with
2014-01-22 16:10:23 +04:00
```
$ git diff --check
```
2013-12-10 21:11:21 +04:00
1. Make sure your commit messages are along the lines of:
Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
2014-10-15 17:09:53 +04:00
2013-12-10 21:11:21 +04:00
Further paragraphs come after blank lines.
2014-10-15 17:09:53 +04:00
2013-12-10 21:11:21 +04:00
- Bullet points are okay, too
2014-10-15 17:09:53 +04:00
2013-12-10 21:11:21 +04:00
- Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here
1. Make sure you have added any necessary tests for your changes.
2015-03-29 19:10:03 +03:00
1. Run all the tests to ensure nothing else was accidentally broken.
2013-12-10 21:11:21 +04:00
2014-01-22 16:10:23 +04:00
```
$ make test
```
2013-12-10 21:11:21 +04:00
1. Push your changes to a topic branch in your fork of the repository.
2014-01-22 16:10:23 +04:00
```
$ git push origin fix/master/my_contrib
```
2013-12-10 21:11:21 +04:00
1. Go to GitHub and submit a pull request to `idris-dev`
From there you will have to wait on one of the `idris-dev` committers to respond to the request.
This response might be an accept or some changes/improvements/alternatives will be suggest.
We do not guarantee that all requests will be accepted.
2015-03-29 19:10:03 +03:00
## Increasing chances of acceptance.
2013-12-10 21:11:21 +04:00
To help increase the chance of your pull request being accepted:
1. Run the tests.
2015-03-29 19:10:03 +03:00
1. Update the documentation, the surrounding code, examples elsewhere, guides, whatever is affected by your contribution
2015-03-19 23:02:37 +03:00
1. Use appropriate code formatting for both Idris and Haskell.
2013-12-10 21:11:21 +04:00
## Additional Resources
* [Idris Wiki ](https://github.com/idris-lang/Idris-dev/wiki );
* [Zen Of Idris ](https://github.com/idris-lang/Idris-dev/wiki/The-Zen-of-Idris );
2016-05-10 15:34:58 +03:00
* Idris FAQs: [Official ](https://idris.readthedocs.io/en/latest/faq/faq.html ); [Unofficial ](https://github.com/idris-lang/Idris-dev/wiki/Unofficial-FAQ );
2013-12-10 21:11:21 +04:00
* [Idris Manual ](https://github.com/idris-lang/Idris-dev/wiki/Manual );
2016-05-10 15:34:58 +03:00
* [Idris Tutorial ](https://idris.readthedocs.io/en/latest/tutorial/index.html );
2019-12-19 16:24:06 +03:00
* [Idris News ](https://www.idris-lang.org/news/ );
* [other Idris docs ](https://www.idris-lang.org/documentation/ ).
2013-12-10 21:11:21 +04:00
* [Using Pull Requests ](https://help.github.com/articles/using-pull-requests )
* [General GitHub Documentation ](https://help.github.com/ ).
2015-10-12 07:25:54 +03:00
Adapted from the most excellent contributing files from the [Puppet project ](https://github.com/puppetlabs/puppet ) and [Factory Girl Rails ](https://github.com/thoughtbot/factory_girl_rails/blob/master/CONTRIBUTING.md )