|
|
| (8 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__
| |
| − | <<[[TableOfContents]]()>>
| |
| − | = Life with bzr and Launchpad =
| |
| | | | |
| − | [[BzrPerfectWorkflow]] contains a high-level overview of what we're trying to achieve. Alternatively, [[GitBzrInstructions]] contains a tutorial on how to use launchpad with git.
| + | <!-- #REDIRECT [[GerritWorkflow]] --> |
| − | | |
| − | == Work flow examples ==
| |
| − | | |
| − | === Getting set up ===
| |
| − | | |
| − | The metadata of a bzr commit contains a name and e-mail of the author and committer (usually the same, but can differ). So, you need to let bzr know who you are:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr whoami "Soren Hansen <soren.hansen@rackspace.com>"
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | This will set this user id globally. It can be set on a per-branch basis as well using the --branch option while in the relevant branch:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr whoami --branch "Soren Hansen <soren@ubuntu.com>"
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | This is useful if you have more than one affiliation.
| |
| − | | |
| − | To make the most of the Launchpad integration, you also tell bzr your Launchpad id if you have registered an SSH key:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr lp-login soren
| |
| − | </nowiki></pre> | |
| − | | |
| − | | |
| − | Now you're ready to rock and roll!
| |
| − | | |
| − | === A day in the life of a bzr user ===
| |
| − | | |
| − | '''Note''': We're walking through all of the bits here for completeness, some of the workflow elements are already automated, or are in the process of being automated away)
| |
| − | | |
| − | bzr keeps it branch data in a .bzr in the top level of your source tree. If you expect to have more than one branch of a project (which is usually the case), you start out by creating a top level directory for the project:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ mkdir ~/src/nova
| |
| − | $ cd ~/src/nova
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Now, let bzr know that it should use this for data shared between the individual branches:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr init-repo .
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Without this, bzr would copy all the branch data when you create a new branch, so this saves time and space.
| |
| − | | |
| − | Now, check out the project:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr branch lp:nova trunk
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | This will grab the designated trunk branch of nova from Launchpad.
| |
| − | | |
| − | The typical workflow from here is to create a branch specific to the feature or bug you're about to work on. Say we want to work on bug number 765432 on Launchpad and we're not creative enough to come up with a descriptive name for the branch:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr branch trunk lp765432
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | This will create a new directory, lp765432, with a new working tree in it, ready for hacking.
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ vim nova/endpoint/api.py
| |
| − | <hack> <hack>
| |
| − | $ bzr commit --fixes lp:765432 -m 'Updated the url argument sort method to ensure a C locale while sorting.'
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | '''Note''': If you omit the -m argument, bzr will open up an editor for you to enter a message, as you would expect.
| |
| − | | |
| − | So far, this branch only lives locally. You want it reviewed, so you push it to Launchpad:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr push lp:~soren/nova/lp765432
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Every user, affiliated with the project or not, can push a nova branch to Launchpad. No special permissions are required. The general URL form is:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | lp:~username/projectname/branchname
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Once it's been pushed, Launchpad will notice the fact that we specified "--fixes lp:765432" while committing and show a link to the branch in the bug. Anyone subscribed to the bug will get an e-mail about this update.
| |
| − | | |
| − | The branch is immediately visible on Launchpad at https://code.launchpad.net/~soren/nova/lp765432. You can also get a listing of all of your branches for a particular project at https://code.launchpad.net/~soren/nova
| |
| − | | |
| − | Note: it's also possible to manually link a bug to a branch from the Launchpad web interface. This is occasionally handy if the bug is tricky and takes a while to fix, and you want people to be able to follow your progress (in case they're curious or perhaps want to help out).
| |
| − | | |
| − | Maybe you decide it needs more work, so you hack on it some more:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ vim nova/endpoint/api.py
| |
| − | <hack> <hack>
| |
| − | $ bzr commit -m 'Try multiple locales while sorting URL arguments to avoid breaking clients that are not careful to do this. This should be considered a temporary fix.'
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Since you've already pushed this branch to Launchpad once before, bzr knows to push it to the same place without more hand holding:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $ bzr push
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | At this point, you want to land this branch into a target branch - typically the trunk branch, but also potentially a long-running feature branch. [[OpenStack]] projects will follow the Patch Queue Manager approach, where a non-human user acts as gatekeeper to trunk and only merges approved branches that pass tests.
| |
| − | | |
| − | ==== Submitting Code to the Patch Queue Manager ====
| |
| − | | |
| − | For formal code review, Launchpad offers a concept called Merge Proposals:
| |
| − | | |
| − | On the branch page, you will see a "Propose for Merging" link. Clicking this will create a Merge Proposal for your branch, by default targetted to the development focus of the project. You can add a note about the proposal, and optionally you can add a commit message to be used when this proposal has landed.
| |
| − | | |
| − | The Merge Proposal is where all things code-review related happen. The code review process is a conversation that can happen over email or through the web interface. Developers can vote on the proposal (approve, deny, etc) and additionally the proposal itself has statuses (Approved, Rejected, Work In Progress). When a Merge Proposal changes status is a project policy decision.
| |
| − | | |
| − | If as the result of conversation or review the branch author decides more work is needed and he will resubmit later, he can simply set the status on the Merge Proposal to "Work In Progress" which will remove it from the review queues. When he's ready for review again, he can either set the status back to "Needs Review" - or he can click the "resubmit proposal" link, which will submit a brand new proposal which contains and references the original one. This can be useful if enough work has been done that original review votes should be cast again.
| |
| − | | |
| − | Once two people have cast votes in approval of the branch, the Merge Proposal may have its status set to "Approved" and a commit message added to it if one is not already there. Once this is done, the Patch Queue Manager (Tarmac) will take over.
| |
| − | | |
| − | Tarmac will at intervals scan for approved merge proposals which have commit messages associated with them and automatically merge each of them, run the unit tests, and push them to the trunk if the trunk is clean. If there is a problem with the merge, the Patch Queue Manager will report the problem as a comment on the merge proposal and reset the merge proposal status to Work In Progress.
| |
| − | | |
| − | === Working with Blueprints ===
| |
| − | | |
| − | Blueprints offer a forum for listing and planning specifications for work to be done. Whereas one could think of these as bugs with a "Feature Request" priority, there is actually a more fundamental difference. A bug is a description of a problem, and a blueprint is a description of a solution. It would be perfectly legitimate, given the scope of a particular problem, to file a bug on a problem and then to write up a blueprint describing the approach to solving the problem. For most bugs this would be a rather large waste of time, but is merely pointed out to underscore the difference in purpose.
| |
| − | | |
| − | The Blueprint system itself is quite simple, and the only thing required to create a blueprint is a title and a description of the blueprint. It is expected that longer-form official writeups of the approach would go on a wiki page, and accordingly the blueprint has a field for specifying where the writeup can be found. The intent here is that if you write a proper description of the work in the wiki, then once you are done with it you will be left with some form of documentation describing a particular feature.
| |
| − | | |
| − | Blueprints, like bugs, can be targeted towards different release series and different milestones, so that at any point it's simple to see what the status of intended work is.
| |
| − | | |
| − | Blueprints can also be used as the basis for planning in-person meetings. Launchpad contains a facility to register meetings, and blueprints can be targeted to available meetings as an element of agenda.
| |
| − | | |
| − | ==== Adding a Blueprint ====
| |
| − | | |
| − | Adding a blueprint is simply a matter of going to the project's blueprints page, such as
| |
| − | | |
| − | <pre><nowiki>
| |
| − | https://blueprints.launchpad.net/nova
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | and clicking on "Register a Blueprint"
| |
| − | | |
| − | ==== Assigning a Blueprint ====
| |
| − | | |
| − | Blueprints carry metadata about who wrote the spec, who approved the spec and who is implementing the spec. If there is a blueprint that you are going to be working on, simply change the assingee to yourself and off you go.
| |
| − | | |
| − | ==== Updating Status ====
| |
| − | | |
| − | Blueprints carry a status field about the relative status of the work. Although not strictly necessary, updating this status removes the need to constantly answer questions from your manager of "what's the status on project X"
| |
| − | | |
| − | ==== Linking a branch ====
| |
| − | | |
| − | Once there is code related to a blueprint, it's a good idea to link that branch to the blueprint, so that someone looking at the blueprint can see that there is a branch in progress.
| |
| − | | |
| − | == Resources and Gotchas ==
| |
| − | | |
| − | The folks at Canonical have a couple of pages up that may be useful for folks migrating
| |
| − | | |
| − | http://doc.bazaar.canonical.com/migration/en/survival/bzr-for-git-users.html
| |
| − | | |
| − | http://doc.bazaar.canonical.com/migration/en/survival/bzr-for-hg-users.html
| |
| − | | |
| − | === Adding Files ===
| |
| − | | |
| − | For folks coming from git, the bzr add command may be a source of some confusion and consternation. In bzr, all changes made to any file in the tree are automatically included in bzr commit, so one does not add files to the index before committing. In bzr, the add command is used to add newly added files to the branch. It is therefore important to remember to run bzr add after creating a new file or directory, but really no other times.
| |
| − | | |
| − | === Rebasing ===
| |
| − | | |
| − | Another gotcha for folks coming from git will be workflow differences around rebasing. Simply put, while rebasing can be done in bzr, it is not a part of the standard workflow and should be avoided in most cases.
| |
| − | ----
| |
| − | [[Category:HowTo]]
| |
