Package com.atlassian.bitbucket.scm.pull

Interface BulkRescopeContext

All Superinterfaces:
Iterable<PullRequestRescope>
public interface BulkRescopeContext extends Iterable<PullRequestRescope>
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}.
Since:
4.5

  • Method Summary

    Modifier and Type
    Method
    Description
    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, com.atlassian.bitbucket.pull.RescopeDetails addedCommits, com.atlassian.bitbucket.pull.RescopeDetails removedCommits)
    Marks the rescope as updating one or both of the associated pull request's from and to refs.

    Methods inherited from interface java.lang.Iterable

    forEach, iterator, spliterator

  • Method Details

    • decline

      void decline(@Nonnull PullRequestRescope rescope)
      Marks the rescope as declining the associated pull request.
      Parameters:
      rescope - the rescope
      Throws:
      IllegalArgumentException - if the provided rescope was not returned by this context

    • getMaxCommitIds

      int getMaxCommitIds()
      Returns:
      the maximum number of commit IDs to provide in update(PullRequestRescope, RescopeDetails, RescopeDetails)

    • merge

      void merge(@Nonnull PullRequestRescope rescope, @Nullable String mergeHash)
      Marks the rescope as remotely merging the associated pull request.

      When a pull request is remotely merged, the SCM can optionally detect and provide the commit which actually carried out the merge. It is only required to detect that the pull request's refs have changed in a way which removes all of the pull request's incoming commits.

      Parameters:
      rescope - the rescope
      mergeHash - the merge hash
      Throws:
      IllegalArgumentException - if the provided rescope was not returned by this context

    • update

      void update(@Nonnull PullRequestRescope rescope, @Nonnull com.atlassian.bitbucket.pull.RescopeDetails addedCommits, @Nonnull com.atlassian.bitbucket.pull.RescopeDetails removedCommits)
      Marks the rescope as updating one or both of the associated pull request's from and to refs.

      The SCM is required to not only detect that the rescope does not merge or decline the pull request, it is also required to detect how many and which commits were added and/or removed from the scope of the pull request.

      For performance reasons, only a limited number of commit IDs should be returned. Implementors should call getMaxCommitIds() to discover how many commit IDs can be returned.

      Parameters:
      rescope - the rescope
      addedCommits - details about how many and what commits were added to the the pull request
      removedCommits - details about how many and what commits were removed from the pull request
      Throws:
      IllegalArgumentException - if the provided rescope was not returned by this context