@@ -0,0 +1,59 @@
1+# Cloud Haskell contributor guidelines
3+See [README](README.md) for how to build from source.
5+The Cloud Haskell project is made up of a number of independent
6+repositories. The cloud-haskell repository includes all other
7+repositories as submodules, for convenience. If you want to hack on
8+any Cloud Haskell package and contribute changes upstream, don't
9+checkout each individual repository in its own directory. Instead (if
10+you have [hub][hub] installed),
13+$ hub clone --recursive haskell-distributed/cloud-haskell
16+which clones all Cloud Haskell repositories as submodules inside the
17+`cloud-haskell` directory. You can then hack on each submodule as
18+usual, committing as usual.
20+[hub]: https://hub.github.com/
22+## Contributing changes upstream
24+### Contributing changes to a single package
26+To contribute changes, you first need a fork:
33+Then publish branches and submit pull requests as usual:
36+$ stack test # Check that everything works before proceeding.
37+$ git push --set-upstream <username> <branch-name>
41+### Contributing related changes to multiple packages
43+The vast majority of changes only affect a single package. But some
44+changes break compatibility with older versions of dependent packages.
45+In this case, you need to submit a separate PR for each package.
52+in the top-level repository to test that all packages work together.
53+Submit the PR's as in the single package case, then additionally
54+follow the same instructions to submit a PR against the
55+`cloud-haskell` repository. This PR should normally only include
56+updates to the submodule references. The objective of this PR is to
57+kick the CI system into providing evidence to the Cloud Haskell
58+maintainers that with all the related changes to each package the
59+whole does compile and pass tests.