From The Linux Foundation
Contents |
Patch Queue Manager
Access to official Linux Foundation Bazaar-NG trees is controlled by the Patch Queue Manager (PQM), a system for requesting automatic merges from external branches. Bazaar-NG User Branches are not so managed; each branch owner is responsible for his or her own user branch.
Rationale
Bazaar is a distributed version control system; this means that, instead of a central repository that everyone writes to, everyone has their own repository. With a system like this, developers need a way to coordinate their changes.
The bzr development team maintains a semi-centralized branch for doing this. Updates to this branch are managed automatically via the Patch Queue Manager software. Anyone with the right to access PQM can request a merge, which is then done automatically, and the results sent back to the developer. Other developers then periodically pull down the latest changes when they need to. No feature or bug fix is considered complete until it's been merged into the central branch via PQM.
Software
The software is distributed via bzr, with no formal releases. There is an official bzr upstream tree, and we also maintain a local branch with some customizations and bug fixes.
Workflow
Developers with access to PQM will typically work something like this:
- A developer creates a local branch of an official LF project.
- This developer makes her changes to this branch, committing every so often.
- As part of this development, she publishes her branch somewhere so others can see her changes, create branches of their own from hers, etc.
- When the changes are ready, she makes sure her published branch is up-to-date.
- She then goes to the official branch project page on bzr.linux-foundation.org, and selects the "merge" option on the top menu.
- After logging in, she fills in the web form with the URL to her published branch, her E-mail address, and a short description of the changes made, and clicks "Submit". The form confirms that the request has been submitted.
- A short while later, after PQM runs, she receives an E-mail reporting whether the merge succeeded. If it failed, she fixes the problems that caused the failure and re-submits a merge request. If it succeeded, her changes will now be available in the official tree.
- The developer synchronizes her branch to reflect that her changes have been merged, and the process starts again.
Some of these steps deserve further explanation.
Publishing
Publishing branches with local changes is a very important part of the workflow. Part of the reason for moving to a distributed model includes giving changes more public QA before they hit the official projects. Obviously, this can't happen if no one besides the original author sees changes until they hit the official trees.
So, while publishing your branch isn't strictly necessary until it's time to merge, it's better to publish early.
If you generally work on one thing at a time in a project, you can publish a single long-lived personal branch. After merging your changes into the official tree, you can "bzr pull" the merge back into your tree; after this point, your branch effectively becomes pristine again, so you can start on something new.
On the other hand, if you tend to have multiple things going on at the same time, you can create branches for each feature, and remove them once they've been merged.
If you need help, you can learn more about publishing branches.
Publishing with Bound Branches
Publishing a branch can be a hassle, because you must stop every so often and copy your working tree to your server. But it doesn't have to be this way; bzr can handle some of the details for you.
Bound branches are branches that work a little like centralized version control systems; when you commit to your working copy, a commit is also done to another copy of your branch elsewhere.
Often, you publish your branch via http, and update it via some ssh protocol (scp, rsync). Typically, this works like this:
bzr branch http://bzr.linux-foundation.org/some/project my-project scp -r my-project my-web-server:/www-path/my-project cd my-project (make changes in my-project) bzr commit rsync -avv * my-web-server:/www-path/my-project (make more changes) bzr commit rsync -avv * my-web-server:/www-path/my-project (...)
Using bound branches, you could do this instead:
bzr branch http://bzr.linux-foundation.org/some/project my-project scp -r my-project my-web-server:/www-path/my-project cd my-projecct bzr bind sftp://my-web-server/www-path/my-project (make changes) bzr commit (make more changes) bzr commit (...)
or:
ssh my-web-server '(cd /www-path && bzr branch http://bzr.linux-foundation.org/some/project my-project)' bzr checkout sftp://my-web-server/www-path/my-project my-project cd my-project (make changes) bzr commit (make more changes) bzr commit (...)
At each commit, bzr sends the commit automatically to the server, asking you for any ssh key passphrases or server passwords as appropriate.
IMPORTANT NOTE: You'll probably need sftp access in bzr to do this, which requires the paramiko python module to be installed. If you get an error like "ERROR: Not a branch: /some/path/sftp:/your/path", it's likely because paramiko is not available on your system.
Pre-Merge Updating
If conflicts are introduced in the merge, PQM will reject it. So, it's generally good practice to resolve those conflicts immediately before requesting a merge.
You can pull in the latest changes in the official tree with "bzr merge". This will pull in the latest changes as uncommitted changes to your working tree. Resolve any conflicts you see, commit the merge, and push it to your published branch.
Synchronizing After Merge
Once PQM reports a successful merge, you can "bzr pull" the merge back into your tree. This will update the logs to reflect upstream's acceptance of your patches. Once you've done that, your branch should be equivalent to upstream, and you can use it for something new or delete it.
Remember that branch revision numbers are local to each branch, so your revno and the official branch's revnos may get out of sync. The revision ids are how bzr tracks changes, though, so it's not a problem.
Alternative Workflow
By popular demand, we have implemented an alternative workflow, which does not require the publication step. Instead, changes are uploaded as a bundle, which is a patch plus the associated bzr commit information.
Requirements
Bundles must be smaller than 8 megabytes in size. You may compress the bundle using gzip if necessary to fit more changes into the uploaded file. If the changes cannot fit, gzipped, into a 8 MB file, then you must publish your branch. (If your changes are that large, it's likely you should publish your changes anyway, so that other developers can review the changes before merging.)
Summary
The workflow is the same in the beginning; users create a local branch, and make all changes there. Instead of publishing the branch, however, the user creates a bundle file, using a command like:
bzr send -o ../my-bundle http://bzr.linux-foundation.org/some/project
Then, the user goes to the official branch project page on bzr.linux-foundation.org, clicks "merge", logs in, and provides her E-mail address and description, as before. Below the place to enter a branch URL, there will be a place to upload a file. The user selects the bundle file created with the "bzr bundle" command, and clicks "Submit". As with the previous workflow, the merge will be queued, and the user will receive the results of the merge in E-mail.