~launchpad-pqm/launchpad/devel

== Create a new merge proposal ==

Branch merge proposals can be created through the API.

    >>> from canonical.launchpad.testing.pages import webservice_for_person
    >>> from canonical.launchpad.webapp.interfaces import OAuthPermission
    >>> from lazr.restful.testing.webservice import pprint_entry
    >>> login('admin@canonical.com')
    >>> target = factory.makeBranch()

    >>> from canonical.launchpad.webapp.servers import WebServiceTestRequest
    >>> request = WebServiceTestRequest(version="beta")
    >>> request.processInputs()

    >>> from lazr.restful.utils import get_current_web_service_request
    >>> request = get_current_web_service_request()

    >>> def fix_url(url):
    ...     """Convert a browser request to a web service client request.
    ...     This is a bit of a hack, but it's the simplest way to get a
    ...     URL that the web service client will respect."""
    ...     return url.replace("launchpad.dev/api/", "api.launchpad.dev/")

    >>> target_url = fix_url(str(canonical_url(
    ...     target, request=request, rootsite='api')))
    >>> source = factory.makeBranchTargetBranch(target.target)
    >>> source_url = fix_url(str(
    ...     canonical_url(source, request=request, rootsite='api')))
    >>> prerequisite = factory.makeBranchTargetBranch(target.target)
    >>> prerequisite_url = fix_url(str(canonical_url(
    ...     prerequisite, request=request, rootsite='api')))
    >>> registrant = source.registrant
    >>> reviewer_url = fix_url(str(canonical_url(
    ...     factory.makePerson(), request=request, rootsite='api')))
    >>> logout()
    >>> registrant_webservice = webservice_for_person(
    ...     registrant, permission=OAuthPermission.WRITE_PUBLIC)
    >>> bmp_result = registrant_webservice.named_post(
    ...     source_url, 'createMergeProposal', target_branch=target_url,
    ...     prerequisite_branch=prerequisite_url,
    ...     initial_comment='Merge\nit!', needs_review=True,
    ...     commit_message='It was merged!\n', reviewers=[reviewer_url],
    ...     review_types=['green'])
    >>> bmp_url = bmp_result.getHeader('Location')
    >>> bmp = registrant_webservice.get(bmp_url).jsonBody()
    >>> pprint_entry(bmp)
    address: u'mp+...@code.launchpad.dev'
    all_comments_collection_link:
        u'http://api.launchpad.dev/devel/~.../+merge/.../all_comments'
    commit_message: u'It was merged!\n'
    date_created: u'...'
    date_merged: None
    date_queued: None
    date_review_requested: u'...'
    date_reviewed: None
    description: u'Merge\nit!'
    merge_reporter_link: None
    merged_revno: None
    prerequisite_branch_link: u'http://api.launchpad.dev/devel/~...'
    preview_diff_link: None
    private: False
    queue_position: None
    queue_status: u'Needs review'
    queued_revid: None
    queuer_link: None
    registrant_link: u'http://api.launchpad.dev/devel/~person-name...'
    resource_type_link:
        u'http://api.launchpad.dev/devel/#branch_merge_proposal'
    reviewed_revid: None
    reviewer_link: None
    self_link: u'http://api.launchpad.dev/devel/~.../+merge/...'
    source_branch_link: u'http://api.launchpad.dev/devel/~...'
    superseded_by_link: None
    supersedes_link: None
    target_branch_link: u'http://api.launchpad.dev/devel/~...'
    votes_collection_link:
        u'http://api.launchpad.dev/devel/~.../+merge/.../votes'
    web_link: u'http://code.../~.../+merge/...'

If we try and create the merge proposal again, we should get a ValueError.

    >>> print registrant_webservice.named_post(
    ...     source_url, 'createMergeProposal', target_branch=target_url,
    ...     prerequisite_branch=prerequisite_url,
    ...     initial_comment='Merge\nit!', needs_review=True,
    ...     commit_message='It was merged!\n', reviewers=[reviewer_url],
    ...     review_types=['green'])
    HTTP/1.1 400 Bad Request
    ...
    There is already a branch merge proposal registered for branch
    ... to land on ... that is still active.

Our review request is listed in the votes collection.

    >>> votes = webservice.get(
    ...     bmp['votes_collection_link']).jsonBody()
    >>> pprint_entry(votes['entries'][0])
    branch_merge_proposal_link: u'http://api.launchpad.dev/devel/~.../+merge/...'
    comment_link: None
    date_created: u'...'
    is_pending: True
    registrant_link: u'http://api.launchpad.dev/devel/~person-name...'
    resource_type_link: u'http://api.launchpad.dev/devel/#code_review_vote_reference'
    review_type: u'green'
    reviewer_link: u'http://api.launchpad.dev/devel/~person-name...'
    self_link: u'http://api.launchpad.dev/devel/~...'

== Get an existing merge proposal ==

Branch merge proposals can be fetched through the API.

    >>> login('admin@canonical.com')
    >>> from lp.code.tests.helpers import (
    ...     make_merge_proposal_without_reviewers)
    >>> fixit_proposal = make_merge_proposal_without_reviewers(factory)
    >>> fixit_proposal.source_branch.owner.name = 'source'
    >>> fixit_proposal.source_branch.name = 'fix-it'
    >>> fixit_proposal.target_branch.owner.name = 'target'
    >>> fixit_proposal.target_branch.name = 'trunk'
    >>> fooix = fixit_proposal.source_branch.product
    >>> fooix.name = 'fooix'
    >>> from lp.code.enums import CodeReviewVote
    >>> comment = factory.makeCodeReviewComment(
    ...     subject='Looks good', body='This is great work',
    ...     vote=CodeReviewVote.APPROVE, vote_tag='code',
    ...     merge_proposal=fixit_proposal)
    >>> comment2 = factory.makeCodeReviewComment(
    ...     subject='Not really', body='This is mediocre work.',
    ...     vote=CodeReviewVote.ABSTAIN, parent=comment,
    ...     merge_proposal=fixit_proposal)
    >>> transaction.commit()

    >>> proposal_url = fix_url(canonical_url(
    ...     fixit_proposal, request=request, rootsite='api'))
    >>> new_person = factory.makePerson()
    >>> target_owner = fixit_proposal.target_branch.owner
    >>> logout()

We use the webservice as an unrelated, unprivileged user.

    >>> webservice = webservice_for_person(
    ...     new_person, permission=OAuthPermission.READ_PUBLIC)

    >>> merge_proposal = webservice.get(proposal_url).jsonBody()
    >>> pprint_entry(merge_proposal)
    address: u'mp+...@code.launchpad.dev'
    all_comments_collection_link: u'http://.../~source/fooix/fix-it/+merge/.../all_comments'
    commit_message: None
    date_created: ...
    date_merged: None
    date_queued: None
    date_review_requested: None
    date_reviewed: None
    description: None
    merge_reporter_link: None
    merged_revno: None
    prerequisite_branch_link: None
    preview_diff_link: None
    private: False
    queue_position: None
    queue_status: u'Work in progress'
    queued_revid: None
    queuer_link: None
    registrant_link: u'http://.../~person-name...'
    resource_type_link: u'http://.../#branch_merge_proposal'
    reviewed_revid: None
    reviewer_link: None
    self_link: u'http://.../~source/fooix/fix-it/+merge/...'
    source_branch_link: u'http://.../~source/fooix/fix-it'
    superseded_by_link: None
    supersedes_link: None
    target_branch_link: u'http://.../~target/fooix/trunk'
    votes_collection_link: u'http://.../~source/fooix/fix-it/+merge/.../votes'
    web_link: u'http://code.../~source/fooix/fix-it/+merge/...'


== Read the comments ==

The comments on a branch merge proposal are exposed through the API.

    >>> all_comments = webservice.get(
    ...     merge_proposal['all_comments_collection_link']).jsonBody()
    >>> print len(all_comments['entries'])
    2
    >>> pprint_entry(all_comments['entries'][0])
    as_quoted_email: u'> This is great work'
    author_link: u'http://api.launchpad.dev/devel/~...'
    branch_merge_proposal_link: u'http://.../~source/fooix/fix-it/+merge/...'
    date_created: u'...'
    id: ...
    message_body: u'This is great work'
    resource_type_link: u'http://.../#code_review_comment'
    self_link: u'http://.../~source/fooix/fix-it/+merge/.../comments/...'
    title: u'Comment on proposed merge of lp://dev/~source/fooix/fix-it into lp://dev/~target/fooix/trunk'
    vote: u'Approve'
    vote_tag: u'code'
    web_link: u'http://code.../~source/fooix/fix-it/+merge/.../comments/...'

    >>> comment_2 = webservice.named_get(
    ...     merge_proposal['self_link'], 'getComment', id=2).jsonBody()
    >>> pprint_entry(comment_2)
    as_quoted_email: u'> This is mediocre work.'
    author_link: u'http://api.launchpad.dev/devel/~...'
    branch_merge_proposal_link: u'http://.../~source/fooix/fix-it/+merge/...'
    date_created: u'...'
    id: ...
    message_body: u'This is mediocre work.'
    resource_type_link: u'http://.../#code_review_comment'
    self_link: u'http://.../~source/fooix/fix-it/+merge/.../comments/...'
    title: ...
    vote: u'Abstain'
    vote_tag: None
    web_link: u'http://code.../~source/fooix/fix-it/+merge/.../comments/...'


== Check the votes ==

The votes on a branch merge proposal can be checked through the API.

    >>> votes = webservice.get(
    ...     merge_proposal['votes_collection_link']).jsonBody()['entries']
    >>> print len(votes)
    2
    >>> pprint_entry(votes[0])
    branch_merge_proposal_link: u'http://.../~source/fooix/fix-it/+merge/...'
    comment_link: u'http://.../~source/fooix/fix-it/+merge/.../comments/...'
    date_created: u'...'
    is_pending: False
    registrant_link: u'http://.../~person-name...'
    resource_type_link: u'http://.../#code_review_vote_reference'
    review_type: u'code'
    reviewer_link: u'http://.../~person-name...'
    self_link: u'http://.../~source/fooix/fix-it/+merge/.../+review/...'


== Performing a Review ==

A review can be performed through the API.

A review can be requested of the person 'target'.

    >>> reviewer_webservice = webservice_for_person(
    ...     target_owner, permission=OAuthPermission.WRITE_PUBLIC)

    >>> person = webservice.get('/~target').jsonBody()
    >>> reviewer = reviewer_webservice.named_post(
    ...     merge_proposal['self_link'], 'nominateReviewer',
    ...     reviewer=person['self_link'], review_type='code')
    >>> print reviewer
    HTTP/1.1 200 Ok ...
    >>> reviewer_entry = reviewer.jsonBody()
    >>> pprint_entry(reviewer_entry)
    branch_merge_proposal_link: u'http://.../~source/fooix/fix-it/+merge/...'
    comment_link: None
    date_created: u'...'
    is_pending: True
    registrant_link: u'http://.../~target'
    resource_type_link: u'http://.../#code_review_vote_reference'
    review_type: u'code'
    reviewer_link: u'http://.../~target'
    self_link: u'http://.../~source/fooix/fix-it/+merge/.../+review/...'

    >>> vote = reviewer_webservice.get(reviewer_entry['self_link'])
    >>> print vote
    HTTP/1.1 200 Ok ...

Now the code review should be made.

    >>> comment_result = reviewer_webservice.named_post(
    ...     merge_proposal['self_link'], 'createComment',
    ...     subject='Great work', content='This is great work',
    ...     vote=CodeReviewVote.APPROVE.title, review_type='code')
    >>> comment_link = comment_result.getHeader('Location')
    >>> comment = reviewer_webservice.get(comment_link).jsonBody()
    >>> pprint_entry(comment)
    as_quoted_email: u'> This is great work'
    author_link: u'http://api.launchpad.dev/devel/~...'
    branch_merge_proposal_link: u'http://.../~source/fooix/fix-it/+merge/...'
    date_created: u'...'
    id: ...
    message_body: u'This is great work'
    resource_type_link: u'http://.../#code_review_comment'
    self_link: u'http://.../~source/fooix/fix-it/+merge/.../comments/...'
    title: ...
    vote: u'Approve'
    vote_tag: u'code'
    web_link: u'http://code.../~source/fooix/fix-it/+merge/.../comments/...'

In fact, now that the votes indicate approval, we might as well set the merge
proposal status to "Approved" as well.

    >>> _unused = reviewer_webservice.named_post(
    ...     merge_proposal['self_link'], 'setStatus',
    ...     status=u'Approved', revid=u'25')
    >>> merge_proposal = reviewer_webservice.get(
    ...     merge_proposal['self_link']).jsonBody()

    >>> print merge_proposal['queue_status']
    Approved
    >>> print merge_proposal['reviewed_revid']
    25

However, there may have been breakage in the branch, and we need to revert back
to "Work In Progress" and not specify the revision_id.

    >>> _unused = reviewer_webservice.named_post(
    ...     merge_proposal['self_link'], 'setStatus',
    ...     status=u'Work in progress')
    >>> merge_proposal = reviewer_webservice.get(
    ...     merge_proposal['self_link']).jsonBody()

    >>> print merge_proposal['queue_status']
    Work in progress
    >>> print merge_proposal['reviewed_revid']
    None


== Updating the preview diff ==

The merge proposal can now be updated with the diff that reflects what the
merge would look like if the source branch was merged into the target branch.

    >>> diff_content = '''\
    ... === modified file 'fooix.txt'
    ... --- fooix.txt\t2009-01-01 12:00:00 +0000
    ... +++ fooix.txt\t2009-02-02 12:34:56 +0000
    ... @@ -206,7 +206,7 @@
    ...  original
    ... -removed
    ... +added
    ... '''
    >>> response = reviewer_webservice.named_post(
    ...     merge_proposal['self_link'], 'updatePreviewDiff',
    ...     diff_content=diff_content,
    ...     source_revision_id='rev-a',
    ...     target_revision_id='rev-b', conflicts='oh, no conflicts')
    >>> print response
    HTTP/1.1 200 Ok
    ...
    Content-Type: application/json
    Vary: ...
    ...

The diff is now visible through the merge proposal.

    >>> merge_proposal = webservice.get(proposal_url).jsonBody()
    >>> preview_diff = webservice.get(
    ...     merge_proposal['preview_diff_link']).jsonBody()
    >>> pprint_entry(preview_diff)
    added_lines_count: 0
    branch_merge_proposal_link:
      u'http://.../~source/fooix/fix-it/+merge/...'
    conflicts: u'oh, no conflicts'
    diff_lines_count: 7
    diff_text_link:
      u'http://.../~source/fooix/fix-it/+merge/.../+preview-diff/diff_text'
    diffstat: {u'fooix.txt': [0, 0]}
    prerequisite_revision_id: None
    removed_lines_count: 0
    resource_type_link: u'http://.../#preview_diff'
    self_link:
      u'http://.../~source/fooix/fix-it/+merge/.../+preview-diff'
    source_revision_id: u'rev-a'
    stale: True
    target_revision_id: u'rev-b'

It is possible that the diff will be empty.

    >>> response = reviewer_webservice.named_post(
    ...     merge_proposal['self_link'], 'updatePreviewDiff',
    ...     diff_content='',
    ...     diff_stat='', source_revision_id='rev-c',
    ...     target_revision_id='rev-d', conflicts=None)
    >>> print response
    HTTP/1.1 200 Ok
    ...
    Content-Type: application/json
    Vary: ...
    ...

== Getting a Project's Pending Merge Proposals ==

It is possible to view all of a project's merge proposals or filter the
proposals by their status.

    >>> def print_proposal(proposal):
    ...     print proposal['self_link'] + ' - ' + \
    ...         proposal['queue_status']


    >>> proposals = webservice.named_get(
    ...     '/fooix', 'getMergeProposals').jsonBody()
    >>> for proposal in proposals['entries']:
    ...     print_proposal(proposal)
    http://.../~source/fooix/fix-it/+merge/... - Work in progress


Or I can look for anything that is approved.

    >>> login('admin@canonical.com')
    >>> from lp.code.enums import BranchMergeProposalStatus
    >>> fixit_proposal.approveBranch(fixit_proposal.target_branch.owner, '1')
    >>> logout()

    >>> def print_proposals(webservice, url, status=None):
    ...     proposals = webservice.named_get(
    ...         url, 'getMergeProposals',
    ...         status=status).jsonBody()
    ...     for proposal in proposals['entries']:
    ...         print_proposal(proposal)

    >>> print_proposals(
    ...     webservice, url='/fooix',
    ...     status=[BranchMergeProposalStatus.CODE_APPROVED.title])
    http://.../~source/fooix/fix-it/+merge/... - Approved

If the branch is private it is not visible to an unpriveleged user.

    >>> login('admin@canonical.com')
    >>> from zope.security.proxy import removeSecurityProxy
    >>> removeSecurityProxy(fixit_proposal.source_branch).explicitly_private = True
    >>> branch_owner = fixit_proposal.source_branch.owner
    >>> logout()

    >>> print_proposals(
    ...     webservice, url='/fooix',
    ...     status=[BranchMergeProposalStatus.CODE_APPROVED.title])

If we get a webservice for the owner of the source branch, then they can see
the proposal if they have allowed the API to access private bits.

    >>> service = webservice_for_person(
    ...     branch_owner, permission=OAuthPermission.READ_PRIVATE)
    >>> print_proposals(
    ...     service, url='/fooix',
    ...     status=[BranchMergeProposalStatus.CODE_APPROVED.title])
    http://.../~source/fooix/fix-it/+merge/... - Approved

    >>> login('admin@canonical.com')
    >>> removeSecurityProxy(fixit_proposal.source_branch).explicitly_private = False
    >>> logout()


== Getting a Person's Pending Merge Proposals ==

It is possible to view all of a person's merge proposals or filter their
proposals by their status.

    >>> proposals = webservice.named_get('/~source', 'getMergeProposals',
    ...     ).jsonBody()
    >>> print_proposals(service, url='/~source')
    http://.../~source/fooix/fix-it/+merge/... - Approved

The person's proposals can also be filtered by status.

    >>> login('admin@canonical.com')
    >>> fixit_proposal.rejectBranch(fixit_proposal.target_branch.owner, '1')
    >>> logout()

    >>> print_proposals(webservice, url='/~source',
    ...     status=[BranchMergeProposalStatus.REJECTED.title])
    http://.../~source/fooix/fix-it/+merge/... - Rejected


== Getting a Project Group's Merge Proposals ==

Getting the merge proposals for a project group will get all the proposals for all
the projects that are part of the project group.

    >>> login('admin@canonical.com')
    >>> project = factory.makeProject(name='widgets')
    >>> fooix.project = project
    >>> blob = factory.makeProduct(name='blob', project=project)
    >>> proposal = factory.makeBranchMergeProposal(
    ...     product=blob, set_state=BranchMergeProposalStatus.NEEDS_REVIEW)
    >>> proposal.source_branch.owner.name = 'mary'
    >>> proposal.source_branch.name = 'bar'
    >>> logout()

By default only work in progress, needs review and approved proposals are
returned.

    >>> print_proposals(webservice, url='/widgets')
    http://.../~mary/blob/bar/+merge/... - Needs review

The proposals can also be filtered by status.

    >>> print_proposals(webservice, url='/widgets',
    ...     status=[BranchMergeProposalStatus.REJECTED.title])
    http://.../~source/fooix/fix-it/+merge/... - Rejected

== Getting Merge Proposals a Person has been Asked To Review ==

It's good to be able to find out which proposals you have been asked to
review.

    >>> login('admin@canonical.com')
    >>> from lp.code.enums import BranchMergeProposalStatus

First we create a review owned by someone else and requested of 'target'
which is the one we want the method to return.

    >>> source_branch = factory.makeBranch(owner=branch_owner,
    ...     product=blob, name="foo")
    >>> target_branch = factory.makeBranch(owner=target_owner,
    ...     product=blob, name="bar")
    >>> proposal = factory.makeBranchMergeProposal(
    ...     target_branch=target_branch,
    ...     product=blob, set_state=BranchMergeProposalStatus.NEEDS_REVIEW,
    ...     registrant=branch_owner, source_branch=source_branch)
    >>> proposal.nominateReviewer(target_owner, branch_owner)
    <CodeReviewVoteReference at ...>

And then we propose a merge the other way, so that the owner is target,
but they have not been asked to review, meaning that the method shouldn't
return this review.

    >>> proposal = factory.makeBranchMergeProposal(
    ...     target_branch=source_branch,
    ...     product=blob, set_state=BranchMergeProposalStatus.NEEDS_REVIEW,
    ...     registrant=target_owner, source_branch=target_branch)
    >>> proposal.nominateReviewer(branch_owner, target_owner)
    <CodeReviewVoteReference at ...>
    >>> logout()

    >>> proposals = webservice.named_get('/~target', 'getRequestedReviews'
    ...     ).jsonBody()
    >>> for proposal in proposals['entries']:
    ...     print_proposal(proposal)
    http://.../~source/blob/foo/+merge/4 - Needs review