For committers, the community has agreed that feature development and architectural changes are best completed in feature branches.  This page is intended to collect as much of the community consensus around how to appropriately go about merging these branches into master, and expectations that the community has of each other.

For contributors, the same rules of thumb apply, although the patch submission process is via reviewboard (See the Review Board Guidelines page for specifics of that process).

Caring for your Branch

This may seem obvious, but periodically pulling updates from master should be important to you.  This will make rebasing prior to a merge request easier.

What makes it "ready to merge"

1. Ensure that any relevant database upgrade scripts are in place prior to the merge (and appropriate to the current master branch's version number)
2. Add unit tests to new classes and methods.  These should be true unit tests, which mock any external system dependencies (i.e.: no database should be required).
3. Add automated integration tests (using Marvin!) or unit-style tests that may require external systems to exist, so that primary test scenarios are modeled and automated.
4. A RAT report shows that there are no license header issues outstanding.
5. Any new dependencies have been discussed and agreed on in the dev list.
6. Legal docs updated in the branch to support any new dependencies.
7. The branch has been rebased against the latest version of master, so that the differences are limited to what's expected to merge (grab the master commit-sh, so that you can point to it in the merge email).
8. Test the build, run unit tests, run integration tests.  Everything should be passing before moving forward with a merge proposal.

Communicating about the merge

Send an email with a "[MERGE]" tag in the subject line to the dev list.  It's useful to point to the design doc on the wiki, the jira record for the work, and any of the critical discussions that talk about the changes.  The reason for an email like this is to help the community understand what the changes will be.  Because of this goal, pointing to the commit-sh in master that tells everyone what point in the master tree they should use to compare the branch with.  Seeing a clean diff is critical to reviewing the proposed merge.

Once you send that email, wait for feedback for at least 72 hours!

If there is any constructive feedback or there are any concerns raised, address them before pushing to master.  Ideally, other community members will want to reach consensus on any issues without formally vetoing a merge, so respect concerns and work to get consensus from the community.

If there are no issues, proceed with your merge.

Example e-mail format:

Hi all,

I would like to merge the feature '_' to master.

JIRA ticket: _
Propsal discussion: _
FS: _
Branch: _
Unit tests: No new unit tests (UI only)
RAT report: _

Thanks
_

Performing the merge

When performing a merge, complete the work in your local repo and then re-run unit tests (as well as any integration tests that you are adding) before pushing to origin.  We want a stable master branch, since it's the shared source tree for the entire community.

Don't walk away after doing the push.  Many other people rely on the master branch, and one of the major goals of this process is to help reduce frustration with changes that break the build.  Wait to confirm that the build works, and be ready to resolve issues if they crop up.