Skip to content

Contributing

Jump to bottom
hyperthunk edited this page Jan 25, 2013 · 3 revisions

Contributor guide

Community contributions are most welcome! These should be submitted via Github's pull request mechanism. Following the guidelines described here will ensure that pull requests require a minimum of effort to deal with, hopefully allowing the maintainer who is merging your changes to focus on the substance of the patch rather than stylistic concerns and/or handling merge conflicts.

This document is quite long, but don't let that put you off! Most of the things we're saying here are just common sense and none of them is hard to follow.

With this in mind, please try to observe the following guidelines when submitting patches.

1. Check to see if your patch is likely to be accepted

To avoid wasting time making changes, only for maintainers to reject your pull request on conceptual grounds, it is best to submit an issue on the github issue tracker in the first instance. This should engender a discussion about the proposed feature (or bugfix), allowing everyone to undertake significant work only when there's confidence the resulting patch is likely to be accepted.

It is also important to work out which component or sub-system should be changed, and whether or not they're best suited to the core Cloud Haskell framework or the Cloud Haskell Platform (which is a feature/utility oriented layer on top of distributed-process).

2. Make sure your patch merges cleanly

Working through pull requests is time consuming and this project is entirely staffed by volunteers. Please make sure your pull requests merge cleanly whenever possible, so as to avoid wasting everyone's time.

The best way to achieve this is to fork the main repository on github, and then make your changes in a local branch. Before submitting your pull request, fetch and rebase any changes to the upstream source branch and merge these into your local branch. For example:

## on your local repository, create a branch to work in

$ git checkout -b bugfix-issue123

## make, add and commit your changes

$ git checkout master
$ git remote add upstream git://github.com/haskell-distributed/distributed-process.git
$ git fetch upstream
$ git rebase upstream/master

## and now rebase (or merge) against your work

$ git checkout bugfix-issue123
$ git merge master

## make sure you resolve any merge conflicts
## and commit before sending a pull request!

3. Follow the patch submission rules of thumb

These are pretty simple and are mostly cribbed from the GHC wiki's git working conventions page here.

  1. try to make small patches - the bigger they are, the longer the pull request QA process will take
  2. strictly separate all changes that affect functionality from those that just affect code layout, indentation, whitespace, filenames etc
  3. always include the issue number (of the form fixes #N) in the final commit message for the patch - pull requests without an issue are unlikely to have been discussed (see above)
  4. use Unix conventions for line endings. If you are on Windows, ensure that git handles line-endings sanely by running git config --global core.autocrlf false
  5. make sure you have setup git to use the correct name and email for your commits - see the github help guide

4. Make sure all the tests pass

If there are any failing tests then your pull request will not be merged. Please don't rely on the maintainers to deal with these, unless of course the tests are failing already on the branch you've diverged from. In that case, please submit an issue so that we can fix the failing tests asap!

5. Try to eliminate compiler warnings

Code should be compilable with -Wall -Werror. There should be no warnings. We may make some exceptions to this rule, but pull requests that contain multitudinous compiler warnings will take longer to QA.

6. Always branch from the right place

Please be aware of whether or not your changes are actually a bugfix or a new feature, and branch from the right place accordingly. The general rule is:

  • new features must branch off development
  • bug fixes must branch off master (which is the stable, production branch)

If you branch from the wrong place then you will be asked to rework your changes so try to get this right in the first place. If you're unsure whether a patch should be considered a feature or a bug-fix then discuss this when opening a new github issue.

General Style

Please carefully review the Style Guide and stick to the conventions set out there as best you can.

Clone this wiki locally