Skip to content

Latest commit

 

History

History
83 lines (59 loc) · 5.28 KB

CONTRIBUTING.adoc

File metadata and controls

83 lines (59 loc) · 5.28 KB
Raw

Contributing to the Git Plugin

The git plugin implements the Jenkins SCM API. Refer to the SCM API documentation for plugin naming conventions and for the preferred locations of new functionality.

Plugin source code is hosted on GitHub. New feature proposals and bug fix proposals should be submitted as GitHub pull requests. Your pull request will be evaluated by the Jenkins job.

Before submitting your change, please assure that you’ve added tests which verify your change. There have been many developers involved in the git plugin and there are many, many users who depend on the git plugin. Tests help us assure that we’re delivering a reliable plugin, and that we’ve communicated our intent to other developers as executable descriptions of plugin behavior.

Compile and test the git plugin with the command:

  • mvn clean verify

Compile the git plugin without running tests using the command:

  • mvn clean -DskipTests verify

Code coverage reporting is available as a maven target. Please improve code coverage with tests when you submit a pull request.

  • mvn -P enable-jacoco clean install jacoco:report to report code coverage

New spotbugs output will fail the build. Do not introduce new spotbugs warnings.

  • mvn spotbugs:check to analyze project using Spotbugs.

  • mvn spotbugs:gui to review Spotbugs report using GUI

Code formatting in the git plugin varies between files. Try to maintain reasonable consistency with the existing files where feasible. Please don’t perform wholesale reformatting of a file without discussing with the current maintainers. New code should follow the SCM API code style guidelines.

Beware: when building locally, some global gitconfig settings can make tests fail. Currently they expect the default branch to be called master. If the default branch has been set to another value than master, it should be temporarily disabled. This is done by adding # before defaultBranch = main in the init section of the .gitconfig file (located in your home directory).

There are enough automated tests in the plugin that it can require more than 60 minutes to complete testing on slower hardware. The buildPlugin() Pipeline shared library limits plugin jobs to 60 minutes and fails them if they take more than 60 minutes. The longest running automated tests have been adapted to have an upper bound on their runtime. Once the runtime set in those long running tests has been reached, new tests in that test class are skipped with the message that the max time was exceeded. Those tests have also been adapted to execute the individuals tests in those classes in random order. By executing the tests in random order, it increases the chances that at least one of the parallel branches of buildPlugin() will execute each test in the long running test classes.

Reviewing Pull Requests

Maintainers triage pull requests by reviewing them and by assigning labels. Release drafter uses the labels to automate release notes.

Others are encouraged to review pull requests, test pull request builds, and report their results in the pull request.

Testing a Pull Request Build

Pull request builds merge the most recent changes from their target branch with the change proposed in the pull request. They can be downloaded from ci.jenkins.io and used to test the pull request. Steps to test a pull request build are:

  1. Find the pull request on GitHub - for example, pull request 676

  2. Find the ci.jenkins.io artifacts for that pull request from the link to the artifacts in the Jenkins job in "Show all checks"

  3. Copy the URL of the hpi file into the "Advanced settings of the Plugin Manager

  4. Restart your Jenkins and you’re ready to test

Reviewing Bug Reports

Git plugin bug reports are assigned to one of the maintainers by default. Open bug reports assigned to a maintainer are assumed to have not been reviewed. When a maintainer completes review of an issue, they include a comment on the bug report and set the 'Assignee' to 'Unassigned'.

Others are welcome to review bug reports, comment on the results of the review, and set the 'Assignee' to 'Unassigned'. Typical bug review tasks include:

  • Review summary and description

  • Attempt to duplicate the issue

  • Add a comment with results of the attempt to duplicate the issue