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:
- Install SBT (the master branch is currently built with SBT 0.12.3).
- 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).
- 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!