Skip to content

Contributor guide

Jump to bottom
Alexandre Chatiron edited this page Jun 24, 2015 · 2 revisions

The best ways to contribute are by finding and reporting bugs, writing tests for bugs, and improving the documentation. We’re always grateful for patches to Play’s code. Indeed, bug reports with attached patches will get fixed far quickly than those without.

If you want to change the code, be careful follow our design-decisions. Be especially careful not to break compatibility with modules and older versions, or to increase complexity if you don't have a really good reason. See also: coding-style guide.

Process to submit a patch

git clone git@github.com:your-username/play1.git my-play-repo
  • Create a branch and switch to it
cd my-play-repo
git branch lighthouse-XXX-patch
git checkout lighthouse-XXX-patch
  • Make your changes, then commit them. Include the lighthouse ticket number at the start of the commit message, eg [#XXX]
git commit -m "[#XXX] Fix something really important"
  • Push the changes from your local branch to your forked repository on github
git push origin lighthouse-XXX-patch
  • Open your forked repository on github at https://github.com/your-username/play1
  • Click "Switch Branches" and select your branch (lighthouse-XXX-patch)
  • Click "Pull Request"
  • Submit your pull request to play developers

Fixing the documentation

The documentation is provided as textile files in the framework distribution. You can contribute to the documentation the same way as for code, or create a ticket with the documentation tag to report issues and contribute corrections and small additions.

Patches review

You're free to fork the main version, apply whatever changes you want and ask us to merge your changes. But we don't give any guarantee that we'll merge your changes. In general, any patch that modifies the core framework interface/life-cycle will probably never be merged. Typically, any patch that change the expected result or behavior of the test suite will be rejected. Tests should only be expanded.

Always include Lighthouse ticket numbers in your commits

Github-Lighthouse integration makes it possible to link github commits and Lighthouse tickets. Contributors should do this, so we can trace changes better:

  • From a git blame to the commit to the ticket, we can understand why a specific line has been changed and see why the code is the way it is
  • From a resolved ticket that came back, we can see how it was fixed in the past and investigate why a regression appeared

This is pretty important for code quality to have this traceability, and it will help us release stable versions more often with confidence. To write a commit message that links to a Lighthouse ticket, include the ticket number like this:

[#42] Fix stuff

You can also fix the ticket directly from the commit if you want. This is not especially useful, since the real value is in linking ticket and commit but feel free to do so if you want. See github commit parsing for details.

Moving forward, with the exception of commits just fixing whitespaces or code style, we should get to the point where every commit has a ticket number. So before you commit, create a Lighthouse ticket if there isn’t one.

Git usage convention.

No one should push changes directly in any branches. All changes should go through a Pull request.

Clone this wiki locally