Development:Branching And Merging Standards
As part of our development we create branches and merge them into trunk. Up until now there have not been any guidelines or standards for these branches and merges.
When do you branch?
- When you are working on a new feature
- When you are fixing a bug
- When you do anything else
- Rule of thumb: Never work in trunk.
Branch Naming Conventions
All branch names should be lowercase, to prevent any possible fun and games later on. Try to make your branch names both short and effective - a difficult combination. Below are some rules for naming branches.
When you're fixing a bug, your branch name should contain the bug number. For example:
$ bzr branch trunk bug-795346
New Feature Branches
Name the branch after the new feature. For example, if your new feature is a ProPresenter song importer:
$ bzr branch trunk propresenter-song-importer
Try to come up with a short, 2 or 3 word summary of your work, and use that. For instance:
$ bzr branch trunk bibles-new-tabs
There are two parts to a merge proposal: proposing, and approving.
Proposing a Merge
- New Merge Proposals
- When you want to propose a merge, make sure you submit a new merge proposal. Do not resubmit old merge proposals.
- Target Branch
- Make sure your target branch is correct. For instance, if you're working on OpenLP itself, the target is lp:openlp, whereas the target for the Android app is lp:openlp/android.
- In addition to that, you need to type in a decent description for your merge proposal. The person reviewing the merge will use your description to determine what the outcome of your merge should be. There are some guidelines below.
- Commit Message
- Not required but highly recommended, setting a commit message allows the person doing the merging to use this instead of making one up from the description.
- Review Process
- If your merge proposal is given at least 1 "Needs Fixing" comment, you need to fix what the commenter has pointed out, and resubmit your merge proposal.
Guidelines for Description:
- Don't write too little. A minimum of one paragraph is required.
- Don't write too much. Usually a small paragraph is sufficient.
- If it's a bug fix, type in both the number and the summary of the bug:
Fixed bug #766201, preview gets messed up if theme edit is canceled.
- If it's a feature, type in a sentence or two about the feature.
- If it's some other fix, type in a short description of what the problem was and your solution.
Approving A Merge
This is mostly for the various teams. Some rules:
- A merge needs to be approved by at least 2 team members.
- The second team member to approve the merge needs to manually set the status to "Approved" (at the top of the proposal).
- If a non-team member proposed it, the second approver needs to commit it.
- If a team member proposed it, they need to commit it.
- If the merge fixes a bug, use the
--fixes lp:XXXXXXargument to link the commit to a bug.
- If merging someone else's proposal, don't forget to add their credentials via
--author "Author Name <email@example.com>".
$ bzr commit -m "Fixed bug #876543: Exception when importing from OpenLP 1.x; fixed a misnamed method." --fixes lp:876543 --author "Tim Buktu <firstname.lastname@example.org>"