Question about implementing Change request support with SCM API

[Goyot, Martin]

Hello everybody,

I'm trying to implement a `branch-source` plugin and I have a question about the support of Change Requests (Pull requests in my case) through the SCM API.

I have read the following documentation (extract from https://github.com/jenkinsci/scm-api-plugin/blob/master/docs/implementation.adoc):

And I checked some implementations, particularly GitLab, Github, BitBucket, Gerrit and Gitea. What I can't wrap my head around is the distinction that is made in the attached part of the documentation between implementing `SCMFileSystem.Builder` and implementing `SCMProbe.stat()`. In which case should I choose the `SCMProbe.stat` over the `SCMFileSystem.Builder` ? The documentation seems to imply that the latter is the "default" way of handling things but I'm not sure I get this correctly. Moreover, after checking the BitBucket plugin for instance, it seems easier to deal with the Probe than it is to deal with the File System Builder.

So questions are:

* When should I choose one over the other ?

* What is the impact of using the Probe instead of the FileSystem. Are there issues with one or the other ?

* Am I missing something ?

Thanks in advance,

Martin

--

Martin Goyot +33.7.66.39.17.39 Consultant and Tuleap trainer Enalean SAS - Tuleap

[Jesse Glick]

On Fri, Apr 23, 2021 at 6:26 AM Goyot, Martin <martin...@enalean.com> wrote:

When should I choose one over the other ?

If possible, implement the full filesystem SPI; else, if possible, implement just the probe.

 

What is the impact of using the Probe instead of the FileSystem.

The probe is used for the limited but critical use case of picking “heads”. For example, someone sets up a multibranch Pipeline using the default recognizer that creates a branch project for each branch (or pull request) with a `Jenkinsfile` at top level. Your probe will be called to check whether a given branch/PR in fact has such a filename.

The filesystem SPI provides richer functionality that supports more features. For example, `Jenkinsfile` can be loaded directly from the SCM somehow, without creating/updating a clone of the repo on the controller filesystem. (“lightweight” vs. “heavyweight checkout”) The `readTrusted` step can also load content directly from a versioned file without doing a full checkout on an agent. This is used implicitly in the `yamlFile` option to Declarative `agent kubernetes`, for example: it would be really annoying to create a generic agent pod just long enough to run an `scm checkout` ~ `git clone` solely to read a single ~1Kb YAML file, then throw away the first pod and create a second one with the actual build environment you want for your project (with some specific version of Ruby tooling, say). Since the `github-branch-source` implements the filesystem SPI, Jenkins is able to retrieve `Jenkinsfile` and `your-build-env.yaml` directly from the GH REST API efficiently, and the repo only ever need be cloned once, on the agent really doing your build.