Skip to end of metadata
Go to start of metadata

This is a landing page for pull requests submitted to Jenkins repositories

Thank you for sending a pull request. The Jenkins project operates bit differently from typical open-source projects, so we provide this document to make sure your pull requests do not fall through the cracks.

Background

Every plugin repository is run differently. Some plugins are maintained by a small number of active contributors who review and gate every change (such as the Artifactory plugin); some plugins are co-maintained by the community and people commit changes when they need (such as the Copy Artifact plugin); and there are other plugins which are dormant with nobody paying attention to the inbound pull requests (such as the Visual SourceSafe plugin.)

This is normal for open-source projects, where people scratch their own itches and move on. For example, Unknown User (stephenconnolly) originally wrote AccuRev Plugin, but since then he changed job and he no longer has access to Accurev, and so naturally he stopped maintaining that plugin. Over time, other people took over the effort, and the last maintainer was helterscelter.

This transition of the implicit maintainership is critical for the overall health of Jenkins project, and so we are always looking for people interested in taking over dormant plugins. And as a person who submitted a pull request, we are trying to recruit you into that.

What to expect

Please give us about a week to respond to your pull request. If the repository in question is actively maintained, this is a sufficient time span for a repository maintainer to acknowledge the pull request you sent.

If an acknowledgement happens, please try to work with the plugin maintainer so that he/she can integrate your changes. This is probably what you are expecting — somebody to review the pull request and merge it.

However, if your pull request doesn't seem to be getting any attention after a week or so, then unfortunately we don't have existing developers reviewing incoming pull requests. Perhaps the repository is not actively maintained any more. In this case, we don't want your pull request to be in limbo forever, you can step forward to become a maintainer of that plugin: see the simple process on https://wiki.jenkins.io/display/JENKINS/Adopt+a+Plugin#AdoptaPlugin-Requestcommitaccess.

What to look for in your changes

In the absence of a review from existing project developers, here is what we'd like you to pay attention to, in determining whether to go ahead and merge the changes:

  • Make sure you didn’t modify portions that aren’t related to your changes (most often caused by IDE auto-fixing import statements and other code formatters.)
  • Be careful about backward compatibility, especially the change in the persisted data such as job configurations. If your change breaks the compatibility, you should be extra careful.
  • If you are adding a feature, is that feature useful to others? Once a feature is released, we can't easily take it back. If it's a feature that's only needed by 3 people in the world, perhaps it could be done as a separate plugin?
  • We encourage you to file a ticket in the issue tracker to describe the bug that you are fixing or the feature you are implementing. This creates the permanent record on our system that later allows future developers to understand how the code came into the current shape. This is not a requirement (especially for small changes), but we appreciate if you do that.
  • Refer to the ticket in your commit message by using the notation [JENKINS-1234] where JENKINS-1234 is the ticket ID. This allows our dumb script to understand the history and generate changelogs without human help. If you use the notation [FIXED JENKINS-1234], our bot will close the ticket automatically when the change is merged into the repository, and when the change is tested in our CI server. These notations create useful cross-references across systems, and are therefore highly recommended.
  • We encourage you to have a test case for the code you added to avoid future regressions. See Unit Test for more details about how to write a test.
  • Try to describe your changes so that other people understand what you did.

FAQs

How do I know if my changes are OK to merge without a review?

This really is a judgement call, and we count on you to do the right thing.

Sometimes, you can just tell that some changes are OK (for example, just editing the text in the help file, adding localizations, or fixing a simple NullPointerException.) Or perhaps you've been using the modified version on your Jenkins installation for some time, which gives you comfort that it works. Or perhaps you see the ticket in the issue tracker showing high interest from other users, which justifies why the change should be integrated.

Sometimes, you can also tell that the changes need further work. Perhaps you didn't write any tests, expecting that the review from existing committers will make up for it. Or perhaps you have some FIXME comments that you wanted the project people to tell you what to do. We'd like you to improve those as much as you can before you push the changes.

What if my change breaks stuff?

It might, and that's a risk the Jenkins project is willing to take. And this is a conscious choice.

We wouldn't be able to scale at all if we screen every new person into the community like Apache does, and we want the plugins to be maintained by those who are using them. If you've figured out how to check out the source code, make changes, and use Maven to build run the changed version, then you probably are smart enough to be a maintainer of the plugin. And above all, the experience shows this served us well.

So we don't want you to cut corners, but please don't get too cautious and don't let your changes go wasted.

  • No labels