lp.code.interfaces.branchmergeproposal.IBranchMergeProposal : API documentation

id =

The tracking number for this question.

whiteboard =

Notes about the merge.

next_preview_diff_job =

The next BranchMergeProposalJob that will update a preview diff.

title =

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.

root_message_id =

Undocumented

@operation_parameters(Int(_('A CodeReviewComment ID.')))
@operation_returns_entry(Interface)
@export_read_operation()
def getComment(id):

Return the CodeReviewComment with the specified ID.

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.

Parameters min_level The minimum notification level needed to be notified.

def isValidTransition(next_state, user=None):

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

@call_with(REQUEST_USER)
@rename_parameters_as('revid')
@operation_parameters(Choice(_('The new status of the merge proposal.'), BranchMergeProposalStatus), Text(_('An optional parameter for specifying the revision of the branch for the status change.'), False))
@export_write_operation()
def setStatus(status, user, revision_id):

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

Parameters	status	The new status of the merge proposal.
	user	The user making the change.
	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.

Parameters	reviewer	A person authorised to review branches for merging.
	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.

Parameters	reviewer	A person authorised to review branches for merging.
	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.

Parameters	merged_revno	The revision number in the target branch that contains the merge of the source branch. (type: `int`)
	date_merged	The date/time that the merge took place.
	merged_revno	(type: `datetime` or a stringified date time value.)
	merge_reporter	The user that is marking the branch as merged. (type: `Person`)

def resubmit(registrant):

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.

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 those 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(Reference(_('A reviewer.'), IPerson), Text())
@call_with(REQUEST_USER)
@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.

Returns A CodeReviewVoteReference or None.

@operation_parameters(Text(), Text(), Choice(CodeReviewVote), Text(), Reference(Interface))
@call_with(REQUEST_USER)
@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.

Parameters	owner	The person who the message is from.
	subject	The subject line to use for the message.
	content	The text to use for the message content. If unspecified, the text of the merge proposal is used.
	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.

Parameters	message	The IMessage to use.
	vote	A CodeReviewVote (or None).
	review_type	A string (or None).
	original_email	Original email message.

def deleteProposal():

Delete the proposal to merge.

@operation_parameters(Bytes(), TextLine(), TextLine(), TextLine(), 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.

Parameters	diff_content	The raw bytes of the diff content to be put in the librarian.
	diff_stat	Text describing the files added, remove or modified.
	source_revision_id	The revision id that was used from the source branch.
	target_revision_id	The revision id that was used from the target branch.
	prerequisite_revision_id	The revision id that was used from the prerequisite branch.
	conflicts	Text describing the conflicts if any.

Int	id	The tracking number for this question.
Whiteboard	whiteboard	Notes about the merge.
Attribute	next_preview_diff_job	The next BranchMergeProposalJob that will update a preview diff.
Attribute	title	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.
Text	root_message_id	Undocumented
Method	getComment	Return the CodeReviewComment with the specified ID.
Method	getRevisionsSinceReviewStart	Return all the revisions added since the review began.
Method	getVoteReference	Return the CodeReviewVoteReference with the specified ID.
Method	getNotificationRecipients	Return the people who should be notified.
Method	isValidTransition	True if it is valid for user update the proposal to next_state.
Method	setStatus	Set the state of the merge proposal to the specified status.
Method	setAsWorkInProgress	Set the state of the merge proposal to 'Work in progress'.
Method	requestReview	Set the state of merge proposal to 'Needs review'.
Method	approveBranch	Mark the proposal as 'Code approved'.
Method	rejectBranch	Mark the proposal as 'Rejected'.
Method	enqueue	Put the proposal into the merge queue for the target branch.
Method	dequeue	Take the proposal out of the merge queue of the target branch.
Method	moveToFrontOfQueue	Move the queue proposal to the front of the queue.
Method	markAsMerged	Mark the branch merge proposal as merged.
Method	resubmit	Mark the branch merge proposal as superseded and return a new one.
Method	isMergable	Is the proposal in a state that allows it to being merged?
Method	getUnlandedSourceBranchRevisions	Return a sequence of `BranchRevision` objects.
Method	nominateReviewer	Set the specified person as a reviewer.
Method	getUsersVoteReference	Get the existing vote reference for the given user.
Method	createComment	Create an ICodeReviewComment associated with this merge proposal.
Method	createCommentFromMessage	Create an `ICodeReviewComment` from an IMessage.
Method	deleteProposal	Delete the proposal to merge.
Method	updatePreviewDiff	Update the preview diff for this proposal.

l.c.i.b.IBranchMergeProposal(IPrivacy) : interface documentation