Contributing

We value all kinds of contributions from the community, not just actual code. Maybe the easiest and yet very good way of helping us improve spray is to ask questions, voice concerns or propose improvements on the Mailing List. Or simply tell us about you or your organization using spray by sending us a small statement for inclusion on the References page.

If you do like to contribute actual code in the form of bug fixes, new features or other patches this page gives you more info on how to do it.

Building spray

Since spray is open-source and hosted on github you can easily build it yourself.

Here is how:

  1. Install SBT (the master branch is currently built with SBT 0.12.3).
  2. Check out the spray source code from the github repository. Pick the branch corresponding to the version you are targeting (check the Current Versions chapter for more info on this).
  3. Run sbt compile test to compile the suite and run all tests.

Contributing documentation

The site, i.e. what you see here at http://spray.io, is built with spray itself. It uses sphinx to generate documentation from reStructured text files located in the docs folder of the spray checkout. The documentation is served from the site sub-project of the sbt build. If you want to contribute documentation make sure you can build and view the site locally. Follow these instructions to get the site project working locally:

  • Follow the instructions in the above section about building spray.
  • Install sphinx (in Debian / Ubuntu install the python-sphinx package, for OS/X see this mailing list thread).
  • Find the path of sphinx-build (in Ubuntu it’s probably /usr/bin/sphinx-build)
  • Set the SPHINX_PATH environment variable to that path.
  • Run sbt
  • In the sbt shell use project site to change into the site project.
  • Use compile to build the site, this will take some time when running for the first time (~ 1 - 3 minutes).
  • Use re-start [1] to start the local site server.
  • Browse to http://localhost:8080
  • Use ~ products in sbt to let it monitor changes to the documentation sources automatically.
  • Edit the documentation files inside the docs subdirectory. After saving a file, it will be automatically picked up by sbt, then it will be regenerated and be available in the browser after ~ 1 - 5 seconds with a refresh of the page.
[1]re-start is a task from the sbt-revolver plugin which starts a project in the background while you can still use the sbt shell for other tasks.

git Branching Model

The spray team follows the “standard” practice of using the master branch as main integration branch, with WIP- and feature branches branching of it. The rule is to keep the master branch always “in good shape”, i.e. having it compile and test cleanly.

Additionally we maintain release branches for older and possibly future releases.

git Commit Messages

We follow the “imperative present tense” style for commit messages (more info here) and begin each message with the module name(s) touched by the commit followed by a colon. Additionally, in order to make it easier for us (and everyone else) to track the effects of changes onto the public API we also explicitly classify every commit into exactly one of three categories:

Category Description Marker
Neutral Only touches things “under the hood” and has no effect on spray’s public API. =
Extending Extends the API by adding things. In rare cases this might break code due to things like identifier shadowing but is generally considered a “safe” change. +
Breaking Changes or removes public API elements. Will definitely break user code relying on these parts of the API surface. !

Apart from the actual Scala interfaces the public API surface covered by these categories also includes configuration settings (most importantly the reference.conf files).

The category that a commit belongs to is indicated with a respective marker character that the commit’s message must start with (followed by a space char), e.g. = testkit: clean up imports. Note that all commits must carry exactly one of the markers listed in the table above, with one exception: merge commits that don’t introduce any changes themselves do not have to carry a marker. Instead, they start with “Merge”. Requiring the marker makes sure that the committer has actively thought about the effects of the commit on the public API surface.

Also, all commits in the “Extending” and especially in the “Breaking” category should contain a dedicated paragraph (in addition to the summary line) explaining in what way the change breaks the API and why this is necessary/beneficial. These paragraphes form the basis of release-to-release migration guides.

Issue Tracking

Currently the spray team uses the Issues Page of the projects github repository for issue management. If you find a bug and would like to report it please go there and create an issue.

If you are unsure, whether the problem you’ve found really is a bug please ask on the Mailing List first.

Contributor License Agreement (CLA)

Contributions to the project, no matter what kind, are always very welcome. However, we would like to make sure that we as the project maintainers as well as the contributors are properly covered with regard to the legal aspects of their contributions. This is why we can only accept patches if the patch is your original work and you license your work to the spray project under the project’s open source license.

In order the provide a proper legal foundation for this we need to ask you to sign our CLA, which is a direct adaptation of the Apache Foundation’s Individual Contributor License Agreement V2.0.

If you have not already done so, please download, complete and sign a copy of the CLA and then scan and email us a PDF file! If you prefer you can also snail-mail us the original, please ask for the mailing address.

Pull Requests

If you’d like to submit a code contribution please fork the github repository and send us pull request against the master branch (or the respective release branch, depending on what version your patch is targeting). Please keep in mind that we might ask you to go through some iterations of discussion and refinements before merging and that you will need have signed a CLA first!