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.
All Cloud Haskell repositories should conform to a common structure, with the exception of website and/or documentation projects. The structure is basically that of a cabal library or executable project, with a couple of additional files.
- project-name
- project-name.cabal
- Makefile
- LICENCE
- README.md
- src/
- tests/
- benchmarks/
- examples/
- regressions/
All repositories must use the same git branch structure:
master branchmastermaster, or from a release-x.y.z branchmaster can be merged in directlymasterWe have a rather full backlog, so your help will be most welcome assisting us in clearing that. You can view the exiting open issues on the jira issue tracker.
If you wish to submit a new issue there, you cannot do so without logging in creating an account (by providing your email address) and logging in.
It is also helpful to work out which component or sub-system should be changed. You may wish to email the maintainers to discuss this first.
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
## add and commit your changes
## base them on master for bugfixes or development for new features
$ 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!
These are pretty simple and are mostly cribbed from the GHC wiki’s git working conventions page here.
PROJECT_CODE #resolve Fixed) in the final commit message for the patch - pull requests without an issue are unlikely to have been discussed (see above)git config --global core.autocrlf falseIf 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!
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.
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:
mastermaster or a release-x.y.z branchIf 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.
A lot of this is taken from the GHC Coding Style entry here. In particular, please follow all the advice on that wiki page when it comes to including comments in your code.
I am also grateful to @tibbe for his haskell-style-guide, from which some of these rules have been taken.
As a general rule, stick to the same coding style as is already used in the file you’re editing. It is much better to write code that is transparent than to write code that is short. Please don’t assume everyone is a minimalist - self explanatory code is much better in the long term than pithy one-liners. Having said that, we do like reusing abstractions where doing so adds to the clarity of the code as well as minimising repetitious boilerplate.
Maximum line length is 80 characters. This might seem antiquated to you, but some of us do things like github pull-request code reviews on our mobile devices on the way to work, and long lines make this horrendously difficult. Besides which, some of us are also emacs users and have this rule set up for all of our source code editing modes.
Tabs are illegal. Use only spaces for indenting. Indentation is usually 2 spaces, with 4 spaces used in some places. We’re pretty chilled about this, but try to remain consistent.
One blank line between top-level definitions. No blank lines between type signatures and function definitions. Add one blank line between functions in a type class instance declaration if the functions bodies are large. As always, use your judgement.
Do not introduce trailing whitespace. If you find trailing whitespace, feel free to strip it out - in a separate commit of course!
Surround binary operators with a single space on either side. Use your better judgement for the insertion of spaces around arithmetic operators but always be consistent about whitespace on either side of a binary operator.
When it comes to alignment, there’s probably a mix of things in the codebase right now. Personally, I tend not to align import statements as these change quite frequently and it is pain keeping the indentation consistent.
The one exception to this is probably imports/exports, which we are a bit finicky about:
import qualified Foo.Bar.Baz as Bz
import Data.Binary
( Binary (..),
, getWord8
, putWord8
)
import Data.Blah
import Data.Boom (Typeable)
We generally don’t care that much about alignment for other things, but as always, try to follow the convention in the file you’re editing and don’t change things just for the sake of it.
Write proper sentences; start with a capital letter and use proper punctuation.
Comment every top level function (particularly exported functions), and provide a type signature; use Haddock syntax in the comments. Comment every exported data type. Function example:
-- | Send a message on a socket. The socket must be in a connected
-- state. Returns the number of bytes sent. Applications are
-- responsible for ensuring that all data has been sent.
send :: Socket -- ^ Connected socket
-> ByteString -- ^ Data to send
-> IO Int -- ^ Bytes sent
For functions, the documentation should give enough information to apply the function without looking at the function’s definition.
Use mixedCase when naming functions and CamelCase when naming data types.
For readability reasons, don’t capitalize all letters when using an abbreviation. For example, write HttpServer instead of HTTPServer. Exception: Two letter abbreviations, e.g. IO.
Use singular when naming modules e.g. use Data.Map and Data.ByteString.Internal instead of Data.Maps and Data.ByteString.Internals.