BulkRescopeContext

Class Overview

Provides a context for SCMs to detect pull request rescopes when a repository is updated.

For the SCM it does not matter what pull request is being rescoped by each of the rescopes. To keep the SPI as simple and flexible as possible, only the repositories and the hashes are made available. The pull requests are not provided. The provided rescopes may be subsequent rescopes of the same pull request, rescopes for different pull requests or a mix. At the SCM level it's irrelevant.

The rescopes are guaranteed to:

• Be non-empty: the oldFromHash will differ from the newFromHash, the oldToHash will differ from the newToHash, or both
• Never have oldFromHash, oldToHash or newToHash equal to null. Only newFromHash can ever be null. A null newToHash would always result in a decline of the pull request, which the system can detect without the SCM. A null newFromHash on the other hand could result in a decline or a merge, depending on whether the from-branch has been merged into the to-branch before it was deleted.

The SCM is required to analyse each of the rescopes and classify it as producing one of four possible outcomes for the associated pull request. Each outcome has a specific contract which SCMs are expected to honour:

• No analysis result: If the result of applying the rescope can not be determined, the SCM shall not call any of the callback methods for it
• If the newFromHash is null, the SCM shall
  • Merge the pull request if the SCM allows updating multiple branches in a single push and the oldFromHash is now reachable from the newToHash, or
  • Decline the pull request if its commits have not been merged to the target
• Merge: If the source or target ref for the pull request has been updated in such a way that there are no commits on the source that are not also on the target, the SCM shall classify the rescope as merging the pull request, with 1 exception (detailed below)
  • SCMs which allow rewriting history must detect cases where such actions effectively remove all of the pending commits from a pull request
  • For example, force pushing a historical commit to the source ref may result in it referencing the same commit as the target ref, or one of its ancestors, effectively making the pull request "merged"
  • If the SCM can detect the commit in which the pull request was merged, the SCM can optionally provide the merge commit ID to the merge callback.
  • If the source ref has been reset to an ancestor of the original target ref, the pull request is "emptied" without being merged and the pull request may be declined.
• Update: If new commits have been added to the source or target refs, the SCM shall classify the rescope as updating the pull request. The SCM shall also detect how many commits, if any, have been added to and removed from the scope of the pull request, which is defined as the commits that are reachable from the source ref, but not the target ref. The SCM shall not provide more than getMaxCommitIds() commit IDs in the addedCommitIds or removedCommitIds lists.
  • There must be at least one commit to be merged, or the pull request shall be marked as merged or declined, not updated
  • SCMs which allow rewriting history must detect when commits are removed from a pull request's source or target refs and update or merge or decline the pull request accordingly

Each rescope in the context may be classified exactly once. Additionally, only rescopes retrieved from the context may be provided back to it for declining, merging or update(PullRequestRescope, RescopeDetails, RescopeDetails) updating}.

Summary

Public Methods
void	decline(PullRequestRescope rescope) Marks the rescope as declining the associated pull request.
int	getMaxCommitIds()
void	merge(PullRequestRescope rescope, String mergeHash) Marks the rescope as remotely merging the associated pull request.
void	update(PullRequestRescope rescope, RescopeDetails addedCommits, RescopeDetails removedCommits) Marks the rescope as updating one or both of the associated pull request's from and to refs.

[Expand] Inherited Methods
From interface java.lang.Iterable void forEach(Consumer<? super T> arg0) Iterator<T> iterator() Spliterator<T> spliterator()