Contribution Guide

This document sets out the development processes for those contributing to the InterMine code base. 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 contributors, 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 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, 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 and 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 and 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.

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 page, and announcements are posted on twitter and the mailing lists and discussed in detail on the community calls.