In this workflow, the mainline branch is shared among a selected set of collaborators, possibly all of them. Collaborators do not commit directly to the mainline, but instead work on new features and bugfixes in local feature branches. When a feature branch is ready, either its author merges it into the mainline or asks another collaborator to perform a review and merge the branch.
There are two main ways of updating the mainline branch:
- Using an unbound branch with pull and push operations
- Using a bound branch with update and commit operations
Both the methods achieve the same result but work slightly differently. Essentially, these are just different working styles of updating remote branches; the preferred method may be a matter of taste.
In the examples demonstrating both the cases, we make the following assumptions:
- Local branches are in a shared repository located at
/sandbox/repo - The URL of the shared mainline branch is
MAINLINE_URL - The URL of the feature branch to merge is
FEATURE_URL
The feature branch to merge may be a remote branch of another collaborator, or your own branch in the local shared repository.
The basic idea of updating the mainline branch using push operations is that you keep a pristine local mirror of the mainline branch, only for the purpose of pull, merge, and push operations.
Before you begin a merge operation, the local mirror must be up-to-date (that is, at the same revision as the mainline), so that after the merge is completed, you can push from it to the mainline.
In a nutshell, the following are the steps to create a local mirror of the mainline branch, merge the feature branch into it, and push the result back into the mainline:
$ cd /sandbox/repo $ bzr branch MAINLINE_URL mainline $ bzr merge FEATURE_URL $ bzr commit -m 'implemented feature X' $ bzr push :parent
There are several things to keep in mind while performing these steps:
- The local mirror of the mainline branch will be created in
/sandbox/repo/mainline, and you should not use it for anything else except for the purpose of merging other branches. Once created, it can be re-used to merge more branches in the future. - If the feature branch is a remote branch, you probably want to create a local branch from it first by using
bzr branch. Before performing the merge, you probably want to inspect the recent revision history of the branch by usingbzr log, and maybe compare it with the mainline by using thebzr missingandbzr difforbzr qdiffcommands. - After performing the merge, you may have to sort out conflicts, possibly contacting the authors of the conflicting changes. Before committing, you should run the various manual and automated non-regression tests of the project, and verify carefully that everything still works well, including the new evolutions introduced by the feature branch.
- When committing the merge, make sure to write an informative log message that summarizes well the changes that were made by the feature branch. Later, when you and other collaborators view the revision history of the project, the intermediary revisions of the feature branch will be hidden by default. Thus it is important to write a nice log message for merge commits.
- In the
bzr pushstep, you can use the:parentshortcut to refer to the parent branch location; in this case, the mainline branch we branched from. After this, Bazaar will save this location as the push branch, so you don't need to specify it again.
At the end of the push operation, the mainline branch and its local mirror will be identical, and you can re-use the local mirror in the future to merge other branches.
While going through the preceding steps, if somebody else adds a change to the mainline, then the last step with the push operation will fail. In this case, you should start over by creating a clean new local mirror and perform the merge again.
If you already have a local mirror of the mainline branch, and you kept it in a clean state without making any local changes, then you can re-use it to merge another branch with the following steps:
$ cd /sandbox/repo/mainline $ bzr pull $ bzr merge FEATURE_URL $ bzr commit -m 'implemented feature X' $ bzr push
The main difference compared to using a clean, new branch is that you can use bzr pull to bring the existing branch up-to-date with the remote mainline branch instead of creating a completely new branch by using bzr branch. This should be slightly faster, because in this case the working tree already exists, and it doesn't need to be completely recreated from scratch.
If you have any pending changes or the branch has diverged from the mainline, then you can overwrite it from the mainline branch by using bzr pull --overwrite, discarding any local changes.
Another minor difference is that you don't need to specify the push location, as it is remembered from the last push operation.
The basic idea of updating the mainline branch using a bound branch is that you keep a pristine checkout of the mainline branch only for the purpose of merging branches.
Before you begin a merge operation, the checkout must be up-to-date (that is, at the same revision as the mainline), so that after the merge is completed, the commit operation will succeed in the mainline.
In a nutshell, these are the steps to create a checkout of the mainline branch, merge the feature branch into it, and commit the result into the mainline:
$ cd /sandbox/repo $ bzr checkout MAINLINE_URL mainline $ bzr merge FEATURE_URL $ bzr commit -m 'implemented feature X'
There are several things to keep in mind while performing these steps:
- The local mirror of the mainline branch will be created in
/sandbox/repo/mainline, and you should not use it for anything else except for the purpose of merging other branches. Once created, it can be re-used to merge more branches in the future. - If the feature branch is a remote branch, you probably want to create a local branch from it first by using
bzr branch. Before performing the merge, you probably want to inspect the recent revision history of the branch by usingbzr log, and maybe compare it with the mainline by using thebzr missingandbzr difforbzr qdiffcommands. - After performing the merge, you may have to sort out the conflicts, possibly by contacting the authors of the conflicting changes. Before committing, you should run the various manual and automated non-regression tests of the project, and verify carefully that everything still works well, including the new evolutions introduced by the feature branch.
- When committing the merge, make sure to write an informative log message that summarizes well the changes that were made by the feature branch. Later, when you and other collaborators view the revision history of the project, the intermediary revisions of the feature branch will be hidden by default. Thus it is important to write a nice log message for merge commits.
Keep in mind that in case of checkouts, the commit operation is applied directly to the master branch; in this case the mainline. After the commit, the two branches will be identical, and you can re-use the checkout in the future to merge other branches.
While going through the preceding steps, if somebody else adds a change to the mainline, then the commit operation will fail, and Bazaar will tell you to run bzr update to bring the checkout up-to-date. If the update operation is successful, you should repeat the non-regression tests and verify carefully that everything still works well. If everything is in order, you can proceed with the commit to complete the merge. Otherwise, if the update operation results in too many conflicts, then it may be better to abort the merge with bzr revert and start over.
If you already have a checkout of the mainline branch, and you kept it in a clean state without making any local changes, then you can re-use it to merge another branch with the following steps:
$ cd /sandbox/repo/mainline $ bzr update $ bzr merge FEATURE_URL $ bzr commit -m 'implemented feature X'
The main difference compared to using a clean new branch is that you can use bzr update to bring the existing branch up-to-date with the remote mainline branch instead of creating a completely new branch by using bzr checkout. This should be slightly faster, because in this case the working tree already exists, and it doesn't need to be completely recreated from scratch.