Contribution Guide
=====================================

This document sets out the development processes for those contributing to the `InterMine code base <https://github.com/intermine/intermine>`_. It specifically refers to the main application code-base, but these practices should be employed in an ideal world on all code bases. 

There is no distinction between the processes that developers should follow internally or externally - all code contributions, whether from core team members or outside contributers, should be treated the same.

Branches
-----------

There are branches in the InterMine GitHub repository with special meaning:

``master``
    The current public release. External users should clone this branch and receive a stable, supported and well-documented application that works to all specifications.

``dev``
    The working branch. Features are merged onto this branch for integration testing. Not guaranteed to be stable.

Setting Up a Development Environment
----------------------------------------

Development does not happen on the master or dev branch. The recommended practice is to fork the `intermine repo <https://github.com/intermine/intermine>`_ and maintain development branches in your own repository.

Developing a Feature
------------------------------------------------

Code contributions should be discrete units of code. They should do one thing (be that fix a bug or add a feature) and not be code dumps. Ideally they should refer to existing issues in the `InterMine issue tracker`. Let's say we want to develop a new feature - discussed in issue ``#12345: We should be better wombles and recycle everything`` - then we would do the following:

1. Checkout the current head of `dev` from upstream.

2. Branch `dev`, naming the branch something descriptive like ``womblier``.

3. Checkout the new branch.

4. Commit, commit, commit. Using detailed commit messages.

5. Push changes to your fork.

6. When you are satisfied that we have reached a sufficiently wombly state of being, then create a new pull request requesting that the head of ``you/womblier`` be merged into ``intermine/dev``.

At any point in the above process you can merge switch to work on another branch and then come back. It is probably a good idea to regularly merge the head of ``intermine/dev`` into ``you/womblier``, especially if development is taking a long time. These merges should probably be ``rebase`` merges.

Hot fix branches (serious bugs that are critical fixes to the current release) should be branched from ``master`` rather than ``dev``, and their pull requests should likewise be for ``master``.

The Role of The Release Manager
-----------------------------------

The release manager's role is to ensure this all happens. They are the only person permitted to push into ``master`` and ``dev``. All code contributions for these branches must pass review by the release manager before they can be merged.

The process for reviewing an merging a pull request is as follows:

1. Read the commits and review the code for style and standards. Request any changes from the developer before proceeding. The criteria for acceptance is:

 * Passing unit test for new code (if applicable)
 * Passes all tests -- according to Travis
 * Documentation (if applicable)
 * Single purpose
 * Detailed commit messages
 * Well commented code
 * Checkstyle

2. Fetch and checkout the new feature branch

3. Merge the target branch (``master`` or ``dev``) into the feature branch. If there are any conflicts push the pull-request back to the developer for resolution.

4. Perform necessary automated and manual testing to verify that this branch is valid.

5. Checkout the current head of ``intermine/dev`` and merge the feature branch into it.

6. Push ``dev`` to the `intermine repo <https://github.com/intermine/intermine>`_.

Release Process
-----------------------------------

Once all pull requests and tickets for a specific milestone are tested and complete, the release manager merges the `dev` branch onto the `master` branch tagging the merge with the milestone's label.  The release notes are available on the `Releases <http://github.com/intermine/intermine/releases>`_ page, and announcments are posted on twitter and the mailing lists and discussed in detail on the community calls.

.. index:: contribution guide, get involved