launchpad help|
Size: 2742
Comment:
|
Size: 6366
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| {{{ Use this template when writing a new page of the Launchpad user guide. Important things to remember: * The table of contents should only remain if there is more than one section. * Keep the "Draft" message until the page has been reviewed and accepted. * Remove these instructions and the "Draft" message before publication. Want to know more? See the DocTeam page. }}} '''DRAFT: this page is a work in progress. Please [[Feedback|seek further help]] or check the [[TitleIndex|wiki index]] for a complete page on this topic.''' |
## page was renamed from Code/Review/Draft ~-[[FrontPage|Launchpad Help]] > [[Code]] > Code review -~ |
| Line 21: | Line 8: |
| Use the first two paragraphs to summarise all the important points about this article. | Thanks to Bazaar's distributed model, you can [[Code/FindingAndDownloading|get full access to the code of any branch]] hosted in Launchpad, with version control and history, right on your own machine. |
| Line 23: | Line 10: |
| Tell the reader if this is the information they need as soon as possible. | That flexibility means you can start work on a project without having to get special permissions to commit code. Of course, if you make changes that you want to see integrated into the project's main line you need a way of telling the main line's owner that you want to merge. |
| Line 25: | Line 12: |
| = Instructional text = | Launchpad and Bazaar make that easy. Bazaar was made to merge: even complex merges can be relatively easy. Launchpad helps look after the community process of discussing whether a proposed merge is a good idea. |
| Line 27: | Line 14: |
| Where appropriate, use step by step instructions: | = Proposing a merge = |
| Line 29: | Line 16: |
| '''Step 1:''' Give concise and unambiguous instructions. | ||<tablestyle="float: right; font-size: 0.8em; width:30%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">{{attachment:proposed-merges.png}}|| ||<style="text-align: center;">'''Proposed merges'''|| |
| Line 31: | Line 19: |
| '''Step 2:''' Try not to state the obvious, unless you're writing for a novice user. | When you've come to a stage in your development where you're ready to merge your code into another branch registered against the project - such as its main line - you can make a public merge proposal. |
| Line 33: | Line 21: |
| {i} '''Note:''' Highlight important information with a note. | To do so, visit your branch's overview page, click ''Propose for merging into another branch'', then follow the on-screen instructions. |
| Line 35: | Line 23: |
| '''Step 3:''' Use a well cropped screen shot if it will help orient the reader. Don't let the screen shot replace instructional text: not everyone can see your screen shot. Don't worry about borders or annotation for small, cropped screen shots such as this. | Now, Launchpad will notify the proposed target branch's owner of your proposal. Anyone viewing the overview page for your branch, or the target branch, will also see a link to view the details of your proposal. |
| Line 37: | Line 25: |
| {{attachment:screen-shot.png}} | == Email interface == |
| Line 39: | Line 27: |
| {i} '''Warning:''' If you're about to tell the reader to delete or otherwise change something that would be hard to restore, warn them. | You can also propose a merge by email by sending a [[http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html#id62|merge directive]] to `merge@code.launchpad.net`. In your email, you can ask for particular people to do the review by adding lines that say: * `reviewer <name>` where `<name>` is the Launchpad user name or email address of the reviewer. You can ask for as many reviewers as you like. Note that you '''must''' start the command line with a space or your command will not be recognized. = Code review = Once you've proposed a merge, anyone who has a Launchpad account can comment and vote on the proposal. Taking part in a code review is virtually hassle-free: * '''no barriers:''' anyone can take part, so long as they have a Launchpad account * '''convenient:''' you can get updates and contribute using email, as well as the web interface. Each review consists of votes - approve, abstain or disapprove - and a threaded conversation much as you might find on a web forum or a mailing list. If you're already familiar with [[Bugs|Launchpad Bugs]], you'll be right at home with code reviews. As a subscriber to the branch or a participant in the code review, you'll receive email updates each time someone adds a vote or message to the review. Just as with the bug tracker, you can take part in the review both by visiting Launchpad's web interface and by replying to any of the emails you receive. In effect, each code review becomes an ad-hoc mailing list that exists for the lifetime of the review. If you want to make your vote specific to one aspect of the proposed merge, you can add a tag. For example: if you wanted to vote disapprove, based on the user interface, you could add a tag of ''ui''. For an example of a review, take a look at a [[https://code.launchpad.net/~therve/storm/binary-and/+merge/387|code review in the Storm project]]. == Email interface == Using the code review email interface is straightforward. Reply to an email from the code review and your comment is added to the discussion in Launchpad. If you want to include commands to modify the approval or status of the review you must sign your email with your GPG key that is associated with your Launchpad account. Here is the list of available commands: Note that you '''must''' start the command line with a space or your command will not be recognized. * `review` - inform the developer what you think of their changes * `review approve` - approve the change ([[http://www.python.org/dev/peps/pep-0010/|alias]]: `+1`) * `review disapprove` - disapprove of the change ([[http://www.python.org/dev/peps/pep-0010/|alias]]: `-1`) * `review abstain` - abstain from deciding ([[http://www.python.org/dev/peps/pep-0010/|alias]]: `-0` and `+0`) * `review resubmit` - tell the developer to rework the change * `review needs_fixing` - tell the developer that a few things need improvement (alias: `needsfixing` and `needs-fixing`) * `merge` - either approve or reject the proposed change * `merge approved` - approve of the merge proposal (alias: `approve`) * `merge rejected` - reject the merge proposal (alias: `reject`) * `reviewer` - add a new reviewer to the merge proposal * `reviewer <name>` where `<name>` is the Launchpad user name or email address of the new reviewer. * `vote` (deprecated: use `review`) * `status` (deprecated: use `merge`) You can combine commands, so if you wanted to vote ''disapprove'', add a tag of ''UI'', leave a comment, and reject the merge proposal, you'd write: {{{ This is a sensible change but I find the user interface confusing. review disapprove UI merge rejected }}} If you simply want to approve the proposal, using `merge approved` will also implicitly add an equivalent `review approve` unless you specify a `review` command separately. |
| Line 42: | Line 81: |
| == Full screen shots == | = Making the merge = |
| Line 44: | Line 83: |
| ||<tablestyle="float:right; font-size: 0.8em; width:30%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">{{attachment:proj-announce.png}}|| ||<style="text-align: center;">'''Describe the screen shot here'''|| |
Once you're ready to merge another branch into yours, follow [[http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html#merging-changes|Bazaar's instructions on merging branches]]. |
| Line 47: | Line 85: |
| Some screen shots will be better placed to the right of your text. As they're not placed directly below the text that they support, use a border and short description. | = Next step = |
| Line 49: | Line 87: |
| Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam sagittis. Aliquam eros dui, scelerisque id, consequat in, accumsan vitae, pede. Suspendisse neque ligula, scelerisque ac, mattis ut, aliquam quis, odio. | You can pick choose which parts of Launchpad you want to use. However, when you use different parts of Launchpad together you can make them work together. Let's look at how you can [[Code/BugAndBlueprintLinks|link bug report and blueprints to branches of code]]. |
| Line 51: | Line 89: |
| Proin nunc nisi, fringilla ac, congue ac, luctus eu, lacus. Maecenas ac purus. Cras felis metus, ultricies non, euismod ac, accumsan eleifend, leo. Quisque imperdiet tempus tellus. Ut euismod, diam nec adipiscing interdum, tortor orci fringilla nisi, vel blandit erat magna at nisi. Fusce hendrerit odio non metus. Mauris nisl massa, dapibus id, feugiat quis, blandit a, quam. Integer tincidunt feugiat nunc. Curabitur iaculis egestas elit. Nam imperdiet suscipit odio. |
||<tablestyle="width: 100%;"> ~-[[Code/TeamBranches|< Team branches]] -~ ||<style="text-align: right;"> ~- [[Code/BugAndBlueprintLinks|Linking branches to bug reports and blueprints >]] -~ || |
Launchpad Help > Code > Code review
Overview
Thanks to Bazaar's distributed model, you can get full access to the code of any branch hosted in Launchpad, with version control and history, right on your own machine.
That flexibility means you can start work on a project without having to get special permissions to commit code. Of course, if you make changes that you want to see integrated into the project's main line you need a way of telling the main line's owner that you want to merge.
Launchpad and Bazaar make that easy. Bazaar was made to merge: even complex merges can be relatively easy. Launchpad helps look after the community process of discussing whether a proposed merge is a good idea.
Proposing a merge
|
Proposed merges |
When you've come to a stage in your development where you're ready to merge your code into another branch registered against the project - such as its main line - you can make a public merge proposal.
To do so, visit your branch's overview page, click Propose for merging into another branch, then follow the on-screen instructions.
Now, Launchpad will notify the proposed target branch's owner of your proposal. Anyone viewing the overview page for your branch, or the target branch, will also see a link to view the details of your proposal.
Email interface
You can also propose a merge by email by sending a merge directive to merge@code.launchpad.net.
In your email, you can ask for particular people to do the review by adding lines that say:
reviewer <name> where <name> is the Launchpad user name or email address of the reviewer.
You can ask for as many reviewers as you like. Note that you must start the command line with a space or your command will not be recognized.
Code review
Once you've proposed a merge, anyone who has a Launchpad account can comment and vote on the proposal. Taking part in a code review is virtually hassle-free:
no barriers: anyone can take part, so long as they have a Launchpad account
convenient: you can get updates and contribute using email, as well as the web interface.
Each review consists of votes - approve, abstain or disapprove - and a threaded conversation much as you might find on a web forum or a mailing list. If you're already familiar with Launchpad Bugs, you'll be right at home with code reviews.
As a subscriber to the branch or a participant in the code review, you'll receive email updates each time someone adds a vote or message to the review. Just as with the bug tracker, you can take part in the review both by visiting Launchpad's web interface and by replying to any of the emails you receive. In effect, each code review becomes an ad-hoc mailing list that exists for the lifetime of the review.
If you want to make your vote specific to one aspect of the proposed merge, you can add a tag. For example: if you wanted to vote disapprove, based on the user interface, you could add a tag of ui.
For an example of a review, take a look at a code review in the Storm project.
Email interface
Using the code review email interface is straightforward. Reply to an email from the code review and your comment is added to the discussion in Launchpad. If you want to include commands to modify the approval or status of the review you must sign your email with your GPG key that is associated with your Launchpad account. Here is the list of available commands:
Note that you must start the command line with a space or your command will not be recognized.
review - inform the developer what you think of their changes
review approve - approve the change (alias: +1)
review disapprove - disapprove of the change (alias: -1)
review abstain - abstain from deciding (alias: -0 and +0)
review resubmit - tell the developer to rework the change
review needs_fixing - tell the developer that a few things need improvement (alias: needsfixing and needs-fixing)
merge - either approve or reject the proposed change
merge approved - approve of the merge proposal (alias: approve)
merge rejected - reject the merge proposal (alias: reject)
reviewer - add a new reviewer to the merge proposal
reviewer <name> where <name> is the Launchpad user name or email address of the new reviewer.
vote (deprecated: use review)
status (deprecated: use merge)
You can combine commands, so if you wanted to vote disapprove, add a tag of UI, leave a comment, and reject the merge proposal, you'd write:
This is a sensible change but I find the user interface confusing. review disapprove UI merge rejected
If you simply want to approve the proposal, using merge approved will also implicitly add an equivalent review approve unless you specify a review command separately.
Making the merge
Once you're ready to merge another branch into yours, follow Bazaar's instructions on merging branches.
Next step
You can pick choose which parts of Launchpad you want to use. However, when you use different parts of Launchpad together you can make them work together. Let's look at how you can link bug report and blueprints to branches of code.
