Background

The existing configuration for the GitHub and Bitbucket SCMSource and SCMNavivator APIs have a very complex UX with multiple checkboxes that have unclear interactions. Furthermore, there are some users who want to modify the behaviour, which would further complicate the UX for all users.

We would like to simplify the configuration for all users and enable the users with specific requirements to be able to address their requirements by extension plugins so that only users with the specific driving use cases need to have the more complex UX.

Acceptance Criteria

After an initial scoping design, the following acceptance criteria have been decided for this refactoring.

 The other Centralized Distributed Version Control System branch sources will likely want to copy this UX refactoring, but this is considered out of scope for this effort.

SCMSource implementations

The SCMSource extension point is used to configure multi-branch projects.

• The basic configuration UI for BitBucket and GitHub must be reduced to the minimum required configuration:
  • API endpoint (if there is more than one server defined).
    If there are no API endpoints defined or only one API endpoint defined and the "Owner" is empty there must be a form validation message hinting that if the user cannot find the owner they are looking for they may need to either change credentials or define a different API endpoint from the current.
  • Credentials
  • Owner (TODO need a better name for Owner)
    • This is the user or organization of the repo
  • Repository
• All other configuration options will be (removed and) provided by extensible strategies
• There will be a strategy to use switch the checkout to over SSH and this will have a option to select the SSH Credentials for checkout.
• There will be at least one strategy to subset the branches by name (include / exclude)
  • There will one implementation that uses the existing wildcard style
  • Other strategies may be added later to support different branch name matching rules, e.g. Regex, etc. These secondary strategies do not form part of the MVP but it may prove assist extension point API validation to proof-of-concept implement a second one.
• There will be three strategies to subset the branches by type:
  • There will be a strategy to select origin branches. This strategy will have a drop-down mode selection:
    • Only origin branches that are not filed as PRs
    • Only origin branches that are filed as PRs
    • All origin branches irrespective of whether filed as PR or not
  • There will be a strategy to select origin PRs. This strategy will have a drop-down mode selection:
    • Merge commit PRs
    • Head commit PRs
    • Both merge commit and head commit PRs
  • There will be a strategy to select fork PRs. This strategy will have a drop-down mode selection:
    • Merge commit PRs
    • Head commit PRs
    • Both merge commit and head commit PRs
• There will also be a drop-down for trust selection:

• • • Show all fork PRs but only trust fork PRs from repository contributors
    • Only show PRs from repository contributors
    • Show and trust all fork PRs
       TBD determine if we need to expose suppression of automatic builds of untrusted PRs here.

• • There will be a proof-of-concept implementation of a tag support branch selector. This is not a feature experienced by users today, but there are api's & code which is ready to provide it. We won't ship this enabled by default in the release.
• There will be the ability to control a subset of the Git plugin’s additional behaviours for the generated SCM of branches. This will be an applies to all setting. The available options will be subject to a whitelisting extension point (so that plugins can define additional Git behaviours and whitelist them in at the same time). The default whitelist will be:
  • Advanced Checkout behaviours
  • Advanced Clone behaviours
  • Advanced Submodule behaviours
  • Clean after checkout
  • Clean before checkout
  • Custom user name / email address
  • Git LFS pull after checkout
  • Use commit author in changelog (says it requires workspace polling, but really does not / should not require workspace polling)
  • Wipe out repository & force clone

 There may be issues with Bitbucket Cloud where the remote repository is a mercurial repository as the mercurial plugin does not provide the additional behaviours of the git plugin. Ideally, if technically possible the Add button would only display the additional behaviours supported by the selected repository type. When used in a SCMNavigator, we have to allow specifying these options without knowing the target repository. It may be that we just use form validation to warn where the repository is known to be mercurial and flag it as not applying in that case.

• By default the additional behaviours of a newly created SCMSource would be:
  • Build origin branches (not PRs)
  • Build origin PRs (merge only)
  • Build fork PRs (merge only, trust contributors only, show all PRs)
  • Clean after checkout

SCMNavigator implementations

For the SCMNavigator (GitHub Org folder or BitBucket Team) implementations:

• The basic configuration UI for BitBucket and GitHub must be reduced to the minimum required configuration:
  • API endpoint (if there is more than one server defined)
  • Credentials
  • Owner (TODO need a better name for Owner)
• All other configuration options will be provided by extensible strategies
• There will be at least one strategy to subset the repositories by name (include / exclude / regex)
• There will be a section to control the generation of the SCMSources that will include all of the extensions from the SCMSource. (e.g., All of the repositories in an org folder will have the same strategies)

Testing / compatibility

• The existing constructors will be @Deprecated and retained and perform the required migration so that existing consumers can create configuration programmatically.
  • There will be @JenkinsRule or other unit tests to verify the functionality of the deprecated constructors.
• The existing instances will be readResolve() mapped to the new configuration model.
  • There will be @JenkinsRule or other unit tests to verify the functionality of the readResolve() methods.
• There will be @JenkinsRule or other unit tests tests to ensure that the current 64 configuration options are mapped correctly for both constructors and readResolve().
• There will be @JenkinsRule tests to ensure that the include / exclude options are converted into extensions correctly for both constructors and readResolve().
• There will be @JenkinsRule tests to ensure that the checkout credentials option is converted into the checkout over SSH extension for both constructors and readResolve().
• There will be @JenkinsRule tests to ensure that the generated GitSCM instances have the configured Git plugin additional behaviours. There will not be tests of these additional behaviours as we assume that the Git plugin provides these requirements.
• The refactoring will enable additional unit tests for the logic of the branch selection strategies. Tests will be written to ensure that bugs like this one are prevented.
• The github-branch-source demo will continue to work.
• There will be a smoke test of the Blue Ocean create-flow, this should be successful as the @Deprecated constructors will have been tested. Detailed coverage of the create-flow is assumed to be already covered by the Blue Ocean acceptance test harness (jamesdumay to confirm)

Documentation

• All new / modified UI form elements will have inline help.
• The wiki pages for the GitHub and BitBucket branch source plugins currently link to the CloudBees user guides. A CloudBees task is that the user guides will be updated to reflect the new UI.
• The user guide content will be ported to jenkins.io/doc (rtyler to confirm exact location). The plugin wiki pages will be updated to point to the jenkins.io/doc documentation