Package io.jenkins.plugins.forensics.reference

Class ReferenceRecorder

java.lang.Object
hudson.tasks.BuildStepCompatibilityLayer
hudson.tasks.Publisher
hudson.tasks.Recorder
io.jenkins.plugins.forensics.reference.SimpleReferenceRecorder
io.jenkins.plugins.forensics.reference.ReferenceRecorder
All Implemented Interfaces:
ExtensionPoint, Describable<Publisher>, BuildStep, SimpleBuildStep
public abstract class ReferenceRecorder extends SimpleReferenceRecorder
Base class for recorders that find reference builds.

Several plugins that report build statistics (test results, code coverage, metrics, static analysis warnings) typically show their reports in two different ways: either as absolute report (e.g., total number of tests or warnings, overall code coverage) or as relative delta report (e.g., additional tests, increased or decreased coverage, new or fixed warnings). To compute a relative delta report, a plugin needs to carefully select the other build to compare the current results to (a so-called reference build). For simple Jenkins jobs that build the main branch of an SCM, the reference build will be selected from one of the previous builds of the same job. For more complex branch source projects (i.e., projects that build several branches and pull requests in a connected job hierarchy) it makes more sense to select a reference build from a job that builds the actual target branch (i.e., the branch the current changes will be merged into). Here one typically is interested what changed in a branch or pull request with respect to the main branch (or any other target branch): e.g., how will the code coverage change if the team merges the changes. Selecting the correct reference build is not that easy, since the main branch of a project will evolve more frequently than a specific feature or bugfix branch.

This recorder unifies the computation of the reference build so consuming plugins can simply use the resulting ReferenceBuild in order to get a reference for their delta reports.

Author:
Arne Schöntag, Ullrich Hafner

  • Constructor Details

    • ReferenceRecorder

      protected ReferenceRecorder()
      Creates a new instance of ReferenceRecorder.

    • ReferenceRecorder

      protected ReferenceRecorder(io.jenkins.plugins.util.JenkinsFacade jenkins)
      Creates a new instance of ReferenceRecorder.
      Parameters:
      jenkins - facade to Jenkins

  • Method Details

    • setLatestBuildIfNotFound

      @DataBoundSetter public void setLatestBuildIfNotFound(boolean latestBuildIfNotFound)
      If enabled, then the latest build of the reference job will be used if no other reference build has been found.
      Parameters:
      latestBuildIfNotFound - if true then the latest build of the reference job will be used if no matching reference build has been found, otherwise no reference build is returned.

    • isLatestBuildIfNotFound

      public boolean isLatestBuildIfNotFound()

    • setTargetBranch

      @DataBoundSetter public void setTargetBranch(String targetBranch)
      Sets the target branch for multi-branch projects: the target branch is considered the base branch in your repository. The builds of all other branches and pull requests will use this target branch as baseline to search for a matching reference build.
      Parameters:
      targetBranch - the name of the default branch

    • getTargetBranch

      public String getTargetBranch()

    • setScm

      @DataBoundSetter public void setScm(String scm)
      Sets the SCM that should be used to find the reference build for. The reference recorder will select the SCM based on a substring comparison, there is no need to specify the full name.
      Parameters:
      scm - the ID of the SCM to use (a substring of the full ID)

    • getScm

      public String getScm()

    • findReferenceBuild

      protected ReferenceBuild findReferenceBuild(Run<?,?> run, edu.hm.hafner.util.FilteredLog logger)
      Overrides:
      findReferenceBuild in class SimpleReferenceRecorder

    • findTargetBranchHead

      protected Optional<jenkins.scm.api.SCMHead> findTargetBranchHead(Job<?,?> job)

    • find

      protected Optional<Run<?,?>> find(Run<?,?> owner, Run<?,?> lastCompletedBuildOfReferenceJob, edu.hm.hafner.util.FilteredLog logger)
      Returns the reference build for the given build owner. The search should start with the last completed build of the reference build. This default implementation does nothing.
      Parameters:
      owner - the owner to get the reference build for
      lastCompletedBuildOfReferenceJob - the last completed build of the reference job
      logger - the logger to use
      Returns:
      the reference build (if available)