~launchpad-pqm/launchpad/devel

# Copyright 2009-2011 Canonical Ltd.  This software is licensed under the

# GNU Affero General Public License version 3 (see the file LICENSE).

# pylint: disable-msg=E0211,E0213

"""The interface for branch merge proposals."""

__metaclass__ = type

__all__ = [

    'BRANCH_MERGE_PROPOSAL_FINAL_STATES',

    'IBranchMergeProposal',

    'IBranchMergeProposalGetter',

    'IBranchMergeProposalJob',

    'IBranchMergeProposalJobSource',

    'IBranchMergeProposalListingBatchNavigator',

    'ICodeReviewCommentEmailJob',

    'ICodeReviewCommentEmailJobSource',

    'ICreateMergeProposalJob',

    'ICreateMergeProposalJobSource',

    'IGenerateIncrementalDiffJob',

    'IGenerateIncrementalDiffJobSource',

    'IMergeProposalNeedsReviewEmailJob',

    'IMergeProposalNeedsReviewEmailJobSource',

    'IMergeProposalUpdatedEmailJob',

    'IMergeProposalUpdatedEmailJobSource',

    'IReviewRequestedEmailJob',

    'IReviewRequestedEmailJobSource',

    'IUpdatePreviewDiffJob',

    'IUpdatePreviewDiffJobSource',

    'notify_modified',

    ]

from lazr.lifecycle.event import ObjectModifiedEvent

from lazr.restful.declarations import (

    call_with,

    export_as_webservice_entry,

    export_factory_operation,

    export_read_operation,

    export_write_operation,

    exported,

    operation_for_version,

    operation_parameters,

    operation_returns_collection_of,

    operation_returns_entry,

    rename_parameters_as,

    REQUEST_USER,

    )

from lazr.restful.fields import (

    CollectionField,

    Reference,

    ReferenceChoice,

    )

from zope.event import notify

from zope.interface import (

    Attribute,

    Interface,

    )

from zope.schema import (

    Bool,

    Bytes,

    Choice,

    Datetime,

    Int,

    Object,

    Text,

    TextLine,

    )

from canonical.database.constants import DEFAULT

from lp import _

from lp.app.interfaces.launchpad import IPrivacy

from canonical.launchpad.webapp.interfaces import ITableBatchNavigator

from lp.code.enums import (

    BranchMergeProposalStatus,

    CodeReviewVote,

    )

from lp.code.interfaces.branch import IBranch

from lp.code.interfaces.diff import IPreviewDiff

from lp.registry.interfaces.person import IPerson

from lp.services.fields import (

    PersonChoice,

    PublicPersonChoice,

    Summary,

    Whiteboard,

    )

from lp.services.job.interfaces.job import (

    IJob,

    IJobSource,

    IRunnableJob,

    ITwistedJobSource,

    )

BRANCH_MERGE_PROPOSAL_FINAL_STATES = (

    BranchMergeProposalStatus.REJECTED,

    BranchMergeProposalStatus.MERGED,

    BranchMergeProposalStatus.SUPERSEDED,

    )

class IBranchMergeProposal(IPrivacy):

    """Branch merge proposals show intent of landing one branch on another."""

    export_as_webservice_entry()

    id = Int(

        title=_('DB ID'), required=True, readonly=True,

        description=_("The tracking number for this merge proposal."))

    registrant = exported(

        PublicPersonChoice(

            title=_('Person'), required=True,

            vocabulary='ValidPersonOrTeam', readonly=True,

            description=_('The person who registered the merge proposal.')))

    source_branch = exported(

        ReferenceChoice(

            title=_('Source Branch'), schema=IBranch, vocabulary='Branch',

            required=True, readonly=True,

            description=_("The branch that has code to land.")))

    target_branch = exported(

        ReferenceChoice(

            title=_('Target Branch'),

            schema=IBranch, vocabulary='Branch', required=True, readonly=True,

            description=_(

                "The branch that the source branch will be merged into.")))

    prerequisite_branch = exported(

        ReferenceChoice(

            title=_('Prerequisite Branch'),

            schema=IBranch, vocabulary='Branch', required=False,

            readonly=True, description=_(

                "The branch that the source branch branched from. "

                "If this branch is the same as the target branch, then "

                "leave this field blank.")))

    # This is redefined from IPrivacy.private because the attribute is

    # read-only. The value is determined by the involved branches.

    private = exported(

        Bool(

            title=_("Proposal is confidential"), required=False,

            readonly=True, default=False,

            description=_(

                "If True, this proposal is visible only to subscribers.")))

    description = exported(

        Text(title=_('Description'), required=False,

             description=_(

                "A detailed description of the changes that are being "

                "addressed by the branch being proposed to be merged."),

             max_length=50000))

    whiteboard = Whiteboard(

        title=_('Whiteboard'), required=False,

        description=_('Notes about the merge.'))

    queue_status = exported(

        Choice(

            title=_('Status'),

            vocabulary=BranchMergeProposalStatus, required=True,

            readonly=True,

            description=_("The current state of the proposal.")))

    # Not to be confused with a code reviewer. A code reviewer is someone who

    # can vote or has voted on a proposal.

    reviewer = exported(

        PersonChoice(

            title=_('Review person or team'), required=False,

            readonly=True, vocabulary='ValidPersonOrTeam',

            description=_("The person that accepted (or rejected) the code "

                          "for merging.")))

    next_preview_diff_job = Attribute(

        'The next BranchMergeProposalJob that will update a preview diff.')

    preview_diff = exported(

        Reference(

            IPreviewDiff,

            title=_('The current diff of the source branch against the '

                    'target branch.'), readonly=True))

    reviewed_revision_id = exported(

        Text(

            title=_(

                "The revision id that has been approved by the reviewer.")),

        exported_as='reviewed_revid')

    commit_message = exported(

        Summary(

            title=_("Commit Message"), required=False,

            description=_("The commit message that should be used when "

                          "merging the source branch."),

            strip_text=True))

    queue_position = exported(

        Int(

            title=_("Queue Position"), required=False, readonly=True,

            description=_("The position in the queue.")))

    queuer = exported(

        PublicPersonChoice(

            title=_('Queuer'), vocabulary='ValidPerson',

            required=False, readonly=True,

            description=_("The person that queued up the branch.")))

    queued_revision_id = exported(

        Text(

            title=_("Queued Revision ID"), readonly=True,

            required=False,

            description=_("The revision id that has been queued for "

                          "landing.")),

        exported_as='queued_revid')

    merged_revno = exported(

        Int(

            title=_("Merged Revision Number"), required=False,

            readonly=True,

            description=_("The revision number on the target branch which "

                          "contains the merge from the source branch.")))

    date_merged = exported(

        Datetime(

            title=_('Date Merged'), required=False,

            readonly=True,

            description=_("The date that the source branch was merged into "

                          "the target branch")))

    title = Attribute(

        "A nice human readable name to describe the merge proposal. "

        "This is generated from the source and target branch, and used "

        "as the tal fmt:link text and for email subjects.")

    merge_reporter = exported(

        PublicPersonChoice(

            title=_("Merge Reporter"), vocabulary="ValidPerson",

            required=False, readonly=True,

            description=_("The user that marked the branch as merged.")))

    supersedes = exported(

        Reference(

            title=_("Supersedes"),

            schema=Interface, required=False, readonly=True,

            description=_("The branch merge proposal that this one "

                          "supersedes.")))

    superseded_by = exported(

        Reference(

            title=_("Superseded By"), schema=Interface,

            required=False, readonly=True,

            description=_(

                "The branch merge proposal that supersedes this one.")))

    date_created = exported(

        Datetime(

            title=_('Date Created'), required=True, readonly=True))

    date_review_requested = exported(

        Datetime(

            title=_('Date Review Requested'), required=False, readonly=True))

    date_reviewed = exported(

        Datetime(

            title=_('Date Reviewed'), required=False, readonly=True))

    date_queued = exported(

        Datetime(

            title=_('Date Queued'), required=False, readonly=True))

    root_message_id = Text(

        title=_('The email message id from the first message'),

        required=False)

    all_comments = exported(

        CollectionField(

            title=_("All messages discussing this merge proposal"),

            # Really ICodeReviewComment.

            value_type=Reference(schema=Interface),

            readonly=True))

    address = exported(

        TextLine(

            title=_('The email address for this proposal.'),

            readonly=True,

            description=_('Any emails sent to this address will result'

                          'in comments being added.')))

    @operation_parameters(

        id=Int(

            title=_("A CodeReviewComment ID.")))

    # Really ICodeReviewComment.

    @operation_returns_entry(Interface)

    @export_read_operation()

    def getComment(id):

        """Return the CodeReviewComment with the specified ID."""

    @call_with(user=REQUEST_USER)

    # Really IBugTask.

    @operation_returns_collection_of(Interface)

    @export_read_operation()

    @operation_for_version('devel')

    def getRelatedBugTasks(user):

        """Return the Bug tasks related to this merge proposal."""

    def getRevisionsSinceReviewStart():

        """Return all the revisions added since the review began.

        Revisions are grouped by creation (i.e. push) time.

        :return: An iterator of (date, iterator of revision data)

        """

    def getVoteReference(id):

        """Return the CodeReviewVoteReference with the specified ID."""

    def getNotificationRecipients(min_level):

        """Return the people who should be notified.

        Recipients will be returned as a dictionary where the key is the

        person, and the values are (subscription, rationale) tuples.

        :param min_level: The minimum notification level needed to be

            notified.

        """

    # Cannot specify value type without creating a circular dependency

    votes = exported(

        CollectionField(

            title=_('The votes cast or expected for this proposal'),

            # Really ICodeReviewVoteReference.

            value_type=Reference(schema=Interface),

            readonly=True,

            )

        )

    def isValidTransition(next_state, user=None):

        """True if it is valid for user update the proposal to next_state."""

    @call_with(user=REQUEST_USER)

    @rename_parameters_as(revision_id='revid')

    @operation_parameters(

        status=Choice(

            title=_("The new status of the merge proposal."),

            vocabulary=BranchMergeProposalStatus),

        revision_id=Text(

            description=_("An optional parameter for specifying the "

                "revision of the branch for the status change."),

            required=False))

    @export_write_operation()

    def setStatus(status, user, revision_id):

        """Set the state of the merge proposal to the specified status.

        :param status: The new status of the merge proposal.

        :param user: The user making the change.

        :param revision_id: The revision id to provide to the underlying

            status change method.

        """

    def setAsWorkInProgress():

        """Set the state of the merge proposal to 'Work in progress'.

        This is often useful if the proposal was rejected and is being worked

        on again, or if the code failed to merge and requires rework.

        """

    def requestReview():

        """Set the state of merge proposal to 'Needs review'.

        As long as the branch is not yet merged, a review can be requested.

        Requesting a review sets the date_review_requested.

        """

    def approveBranch(reviewer, revision_id):

        """Mark the proposal as 'Code approved'.

        The time that the branch was approved is recoreded in `date_reviewed`.

        :param reviewer: A person authorised to review branches for merging.

        :param revision_id: The revision id of the branch that was

                            reviewed by the `reviewer`.

        :raises: UserNotBranchReviewer if the reviewer is not in the team of

                 the branch reviewer for the target branch.

        """

    def rejectBranch(reviewer, revision_id):

        """Mark the proposal as 'Rejected'.

        The time that the branch was rejected is recoreded in `date_reviewed`.

        :param reviewer: A person authorised to review branches for merging.

        :param revision_id: The revision id of the branch that was

                            reviewed by the `reviewer`.

        :raises: UserNotBranchReviewer if the reviewer is not in the team of

                 the branch reviewer for the target branch.

        """

    def enqueue(queuer, revision_id):

        """Put the proposal into the merge queue for the target branch.

        If the proposal is not in the Approved state before this method

        is called, approveBranch is called with the reviewer and revision_id

        specified.

        If None is supplied as the revision_id, the proposals

        reviewed_revision_id is used.

        """

    def dequeue():

        """Take the proposal out of the merge queue of the target branch.

        :raises: BadStateTransition if the proposal is not in the queued

                 state.

        """

    def moveToFrontOfQueue():

        """Move the queue proposal to the front of the queue."""

    def markAsMerged(merged_revno=None, date_merged=None,

                     merge_reporter=None):

        """Mark the branch merge proposal as merged.

        If the `merged_revno` is supplied, then the `BranchRevision` is

        checked to see that revision is available in the target branch.  If it

        is then the date from that revision is used as the `date_merged`.  If

        it is not available, then the `date_merged` is set as if the

        merged_revno was not supplied.

        If no `merged_revno` is supplied, the `date_merged` is set to the

        value of date_merged, or if the parameter date_merged is None, then

        UTC_NOW is used.

        :param merged_revno: The revision number in the target branch that

                             contains the merge of the source branch.

        :type merged_revno: ``int``

        :param date_merged: The date/time that the merge took place.

        :type merged_revno: ``datetime`` or a stringified date time value.

        :param merge_reporter: The user that is marking the branch as merged.

        :type merge_reporter: ``Person``

        """

    def resubmit(registrant, source_branch=None, target_branch=None,

                 prerequisite_branch=DEFAULT):

        """Mark the branch merge proposal as superseded and return a new one.

        The new proposal is created as work-in-progress, and copies across

        user-entered data like the whiteboard.  All the current proposal's

        reviewers, including those who have only been nominated, are requested

        to review the new proposal.

        :param registrant: The person registering the new proposal.

        :param source_branch: The source_branch for the new proposal (defaults

            to the current source_branch).

        :param target_branch: The target_branch for the new proposal (defaults

            to the current target_branch).

        :param prerequisite_branch: The prerequisite_branch for the new

            proposal (defaults to the current prerequisite_branch).

        :param description: The description for the new proposal (defaults to

            the current description).

        """

    def isMergable():

        """Is the proposal in a state that allows it to being merged?

        As long as the proposal isn't in one of the end states, it is valid

        to be merged.

        """

    def getUnlandedSourceBranchRevisions():

        """Return a sequence of `BranchRevision` objects.

        Returns up to 10 revisions that are in the revision history for the

        source branch that are not in the revision history of the target

        branch.  These are the revisions that have been committed to the

        source branch since it branched off the target branch.

        """

    @operation_parameters(

        reviewer=Reference(

            title=_("A reviewer."), schema=IPerson),

        review_type=Text())

    @call_with(registrant=REQUEST_USER)

    # Really ICodeReviewVoteReference.

    @operation_returns_entry(Interface)

    @export_write_operation()

    def nominateReviewer(reviewer, registrant, review_type=None):

        """Set the specified person as a reviewer.

        If they are not already a reviewer, a vote is created.  Otherwise,

        the details are updated.

        """

    def getUsersVoteReference(user):

        """Get the existing vote reference for the given user.

        :return: A `CodeReviewVoteReference` or None.

        """

    @operation_parameters(

        subject=Text(), content=Text(),

        vote=Choice(vocabulary=CodeReviewVote), review_type=Text(),

        parent=Reference(schema=Interface))

    @call_with(owner=REQUEST_USER)

    # ICodeReviewComment supplied as Interface to avoid circular imports.

    @export_factory_operation(Interface, [])

    def createComment(owner, subject, content=None, vote=None,

                      review_type=None, parent=None):

        """Create an ICodeReviewComment associated with this merge proposal.

        :param owner: The person who the message is from.

        :param subject: The subject line to use for the message.

        :param content: The text to use for the message content.  If

            unspecified, the text of the merge proposal is used.

        :param parent: The previous CodeReviewComment in the thread.  If

            unspecified, the root message is used.

        """

    def createCommentFromMessage(message, vote, review_type,

                                 original_email):

        """Create an `ICodeReviewComment` from an IMessage.

        :param message: The IMessage to use.

        :param vote: A CodeReviewVote (or None).

        :param review_type: A string (or None).

        :param original_email: Original email message.

        """

    def deleteProposal():

        """Delete the proposal to merge."""

    @operation_parameters(

        diff_content=Bytes(), source_revision_id=TextLine(),

        target_revision_id=TextLine(), prerequisite_revision_id=TextLine(),

        conflicts=Text())

    @export_write_operation()

    def updatePreviewDiff(diff_content, source_revision_id,

                          target_revision_id, prerequisite_revision_id=None,

                          conflicts=None):

        """Update the preview diff for this proposal.

        If there is not an existing preview diff, one will be created.

        :param diff_content: The raw bytes of the diff content to be put in

            the librarian.

        :param diff_stat: Text describing the files added, remove or modified.

        :param source_revision_id: The revision id that was used from the

            source branch.

        :param target_revision_id: The revision id that was used from the

            target branch.

        :param prerequisite_revision_id: The revision id that was used from

            the prerequisite branch.

        :param conflicts: Text describing the conflicts if any.

        """

class IBranchMergeProposalJob(Interface):

    """A Job related to a Branch Merge Proposal."""

    id = Int(

        title=_('DB ID'), required=True, readonly=True,

        description=_("The tracking number for this job."))

    branch_merge_proposal = Object(

        title=_('The BranchMergeProposal this job is about'),

        schema=IBranchMergeProposal, required=True)

    job = Object(title=_('The common Job attributes'), schema=IJob,

        required=True)

    metadata = Attribute('A dict of data about the job.')

    def destroySelf():

        """Destroy this object."""

class IBranchMergeProposalJobSource(ITwistedJobSource):

    """A job source that will get all supported merge proposal jobs."""

class IBranchMergeProposalJobSource(IJobSource):

    """A job source that will get all supported merge proposal jobs."""

class IBranchMergeProposalListingBatchNavigator(ITableBatchNavigator):

    """A marker interface for registering the appropriate listings."""

class IBranchMergeProposalGetter(Interface):

    """Utility for getting BranchMergeProposals."""

    def get(id):

        """Return the BranchMergeProposal with specified id."""

    def getProposalsForContext(context, status=None, visible_by_user=None):

        """Return BranchMergeProposals associated with the context.

        :param context: Either an `IPerson` or `IProduct`.

        :param status: An iterable of queue_status of the proposals to return.

            If None is specified, all the proposals of all possible states

            are returned.

        :param visible_by_user: If a person is not supplied, only merge

            proposals based on public branches are returned.  If a person is

            supplied, merge proposals based on both public branches, and the

            private branches that the person is entitled to see are returned.

            Private branches are only visible to the owner and subscribers of

            the branch, and to LP admins.

        :raises BadBranchMergeProposalSearchContext: If the context is not

            understood.

        """

    def getProposalsForParticipant(participant, status=None,

        visible_by_user=None):

        """Return BranchMergeProposals associated with the context.

        :param participant: An `IPerson` that is participating in the merge

            proposal, either a reviewer or reviewee.

        :param status: An iterable of queue_status of the proposals to return.

            If None is specified, all the proposals of all possible states

            are returned.

        :param visible_by_user: If a person is not supplied, only merge

            proposals based on public branches are returned.  If a person is

            supplied, merge proposals based on both public branches, and the

            private branches that the person is entitled to see are returned.

            Private branches are only visible to the owner and subscribers of

            the branch, and to LP admins.

        """

    def getVotesForProposals(proposals):

        """Return a dict containing a mapping of proposals to vote references.

        The values of the dict are lists of CodeReviewVoteReference objects.

        """

    def getVoteSummariesForProposals(proposals):

        """Return the vote summaries for the proposals.

        A vote summary is a dict has a 'comment_count' and may also have

        values for each of the CodeReviewVote enumerated values.

        :return: A dict keyed on the proposals.

        """

for name in ['supersedes', 'superseded_by']:

    IBranchMergeProposal[name].schema = IBranchMergeProposal

class ICreateMergeProposalJob(IRunnableJob):

    """A Job that creates a branch merge proposal.

    It uses a Message, which must contain a merge directive.

    """

class ICreateMergeProposalJobSource(IJobSource):

    """Acquire MergeProposalJobs."""

    def create(message_bytes):

        """Return a CreateMergeProposalJob for this message."""

class IMergeProposalNeedsReviewEmailJob(IRunnableJob):

    """Email about a merge proposal needing a review.."""

class IMergeProposalNeedsReviewEmailJobSource(Interface):

    """Interface for acquiring MergeProposalNeedsReviewEmailJobs."""

    def create(bmp):

        """Create a needs review email job for the specified proposal."""

class IUpdatePreviewDiffJob(IRunnableJob):

    """Interface for the job to update the diff for a merge proposal."""

    def checkReady():

        """Check to see if this job is ready to run."""

class IUpdatePreviewDiffJobSource(Interface):

    """Create or retrieve jobs that update preview diffs."""

    def create(bmp):

        """Create a job to update the diff for this merge proposal."""

    def get(id):

        """Return the UpdatePreviewDiffJob with this id."""

class IGenerateIncrementalDiffJob(IRunnableJob):

    """Interface for the job to update the diff for a merge proposal."""

class IGenerateIncrementalDiffJobSource(Interface):

    """Create or retrieve jobs that update preview diffs."""

    def create(bmp, old_revision_id, new_revision_id):

        """Create job to generate incremental diff for this merge proposal."""

    def get(id):

        """Return the GenerateIncrementalDiffJob with this id."""

class ICodeReviewCommentEmailJob(IRunnableJob):

    """Interface for the job to send code review comment email."""

    code_review_comment = Attribute('The code review comment.')

class ICodeReviewCommentEmailJobSource(Interface):

    """Create or retrieve jobs that update preview diffs."""

    def create(code_review_comment):

        """Create a job to email subscribers about the comment."""

class IReviewRequestedEmailJob(IRunnableJob):

    """Interface for the job to sends review request emails."""

    reviewer = Attribute('The person or team asked to do the review. '

                         'If left blank, then the default reviewer for the '

                         'selected target branch will be used.')

    requester = Attribute('The person who has asked for the review.')

class IReviewRequestedEmailJobSource(Interface):

    """Create or retrieve jobs that email review requests."""

    def create(review_request):

        """Create a job to email a review request.

        :param review_request: A vote reference for the requested review.

        """

class IMergeProposalUpdatedEmailJob(IRunnableJob):

    """Interface for the job to sends email about merge proposal updates."""

    editor = Attribute('The person that did the editing.')

    delta_text = Attribute(

        'The textual representation of the changed fields.')

class IMergeProposalUpdatedEmailJobSource(Interface):

    """Create or retrieve jobs that email about merge proposal updates."""