Project Governance Document

We strive for lower barrier of entry to the project. This is partly achieved by not requiring new contributors to “prove themselves” before they are admitted to the committership. Instead, we assume they are good until proven otherwise, and this principle applies to anybody without arbitrary discrimination. We recognize that every contribution is precious, and we recognize that every added process turn away some potential contributors.

The lower barrier of entry is partly achieved by structuring the project to core, plugins, modules, and other independent pieces, thereby reducing the need for collaboration and communication. We try to let everyone have their own turf where they can work efficiently without bogged down by discussions and compromises. We believe everyone has the right to express their idea in their own plugins.

The lower barrier of entry is also partly achieved by recognizing that people move on. Lots of code in the project is maintained by people other than the original author. We encourage new contributors to take over existing projects that aren’t actively maintained. We believe that “old” contributors deserve respect from “new” contributors, but the inaction on the part of the original contributors shall not block new contributors from making changes.

Our striving to lower barrier of entry doesn’t mean everyone has the equal voice. We value those who contribute more to the project, namely Meritocracy. Contribution shouldn’t be narrowly interpreted just to code changes, but rather it includes such activities as helping others in the community, doing PR, running infrastructure, and so on.

We believe in running the project transparently. This includes everything from decision-making to defects in the code.

We recognize that users expect their existing data, accumulated under past versions (including Hudson up to 1.395) to continue working under future versions of Jenkins. This includes jobs configurations, build records, and plugin binaries that they are using. The Jenkins project places high value on maintaining this compatibility, and will be very careful in removing functionality.

To enable the above goal, we also recognize that plugin developers expect APIs and other code that they depend on to remain available in future versions of Jenkins. This is not to say we don’t ever remove anything, but we do it very carefully.

Because one plugin can depend on another, we expect the same principle from plugins that many other plugins depend on.

One of the goals of the Jenkins project is to enable more automation, and we apply the same principle in developing Jenkins. Accordingly, we develop and use a number of daemons, bots, and scripts to perform house-keeping activities and day-to-day operations, we use Jenkins ourselves to run many of those.

This not only frees our time to do more creative work, but it also helps reduce the barrier to entry by reducing the blockage of one developer by another. Plus it has the added benefit of eating our own dogfood.

To further clarify the intellectual property rights around the project, we require that core committers sign a contributor agreement. The Jenkins project uses the EasyCLA service provided by the Linux Foundation. Refer to the infra-cla README for contributor license agreement submission instructions. More details are available from the Linux Foundation for individual contributors and corporate contributors.

EasyCLA is self service and requires no manual intervention by the board or any other Jenkins project member. It is a one-time process, valid for all Jenkins community spaces.

CLAs come in two flavors. Every core contributor needs to sign an Individual CLA (ICLA), and in cases where you as an individual do not own the work you are contributing (such as when your company assigns you to work on Jenkins and therefore your company owns the hard work you produced), the corporation also needs to sign a Corporate CLA (CCLA). See the discussion in Apache for more details. The CLA forms can be obtained by following the documentation in the infra-cla repository.

To balance the additional overhead with the lower barrier to entry, this policy only applies to the core, although we welcome anyone who’s willing to submit a CLA for their work on plugins.

Details to submit CLAs are documented in infra-cla README.

The Jenkins project depends heavily on 3rd party libraries. We believe it’s better to reuse what we can than to reinvent, so that our precious resources can be spent elsewhere.

Jenkins as a whole needs to be an open-source project, so we’ve been restricting ourselves to only use 3rd party libraries that are under OSI-approved (such as Apache Software License, BSD license, MIT license, Eclipse Public License, and Lesser GNU Public License) or public-domain-equivalent licenses or dedicated to the public domain. In addition, to keep the core reusable for the widest possible use cases, we refuse so-called copyleft licenses that restrict the overall license to a specific license (such as GNU Public License.) To that end, we designated the following licenses as approved licenses that we can depend on. Additional licenses are subject to the approval by the board:

In core, the build process ensure that all the licenses of the dependency libraries are accounted for. In other words, we require that dependency POMs declare their own licenses in the Maven way, or use the license completion script to supply one where the POM is missing that information. The completion script is also used in case the library is dual-licensed to pick a specific license. This is done so that the summary list of the 3rd party library licenses do not include copy-left licenses.

The result is packaged into the core and is visible from within the application itself. It is also available in the XML format inside the war file.

Plugins do not necessarily follow the same formality when it comes to the 3rd party license policy. They obviously need to honor the licenses of the libraries they use, but for example they need not run the same license completion scheme that the core uses.

We encourage plugins to follow the same 3rd party license policy as the core. You may vary from it at your own risk. For example, see FSF’s opinion about GPL plugins with a non-GPL core.

The governance board consists of five people who act as public representatives of the project, when such representation is necessary, for example to interface external entities such as SPI or CDF.

The board also acts as the ultimate decision-making authority in case disputes cannot be resolved via the regular project community meeting. The decision-making ability of the board is more symbolic and honorific, and it “rules” like British royalty rather than a dictatorship.

The Governance Board page provides further information, including a list of current board members, and how to contact the board.

The process by which the Governance Board is elected can be reviewed in the Board Election Process

Infrastructure administrators have root access to the various servers and build agents that run jenkins-ci.org and other sub-domains. They keep those servers up and running, installing new software, coordinating mirrors, handling keys and certificates, and making sure that we can keep churning out code.

Because of the sensitive nature of this work, infrastructure admins are by invitation only, and some of the activity happen behind closed doors. Infrastructure admins often appoint others to delegate some partial access to the system to complete some tasks.

Infrastructure components are maintained by the infrastructure project. See the contributing guidelines for more information. Open a help desk issue for infrastructure problems.

Core committers are those who have push access to the main Jenkins repository that produces jenkins.war. To become a core committer, one needs to sign the contributor license agreement. One is not required to have a proven history of contributions before being granted commit access, but that doesn’t mean other core committers will never revert your changes.

The list of CLA signers is be maintained here: https://github.com/jenkinsci/infra-cla

Plugin committers are those who have push access to specific plugin repositories hosted under the jenkinsci GitHub organization. One is not required to have a proven history of contributions before being granted commit access. All you have to do is to ask. But that doesn’t mean other existing committers will never revert your changes.

Localization contributors have push access to both the core and hosted plugins. They make localization/internationalization related changes to the code and resources, and they push those changes without seeking approval from the core/plugin committers.

Users use Jenkins and its plugins. They contribute to the project by providing feedback, filing bug reports, prioritizing features and fixes for developers, helping other users, and making committers feel like their work is worth while.

The Jenkins project provides two release lines for the Jenkins core. For both lines we provide multiple distributions including jenkins.war, Docker images, installers and native packages. They can be downloaded by users here.

Modules are libraries that are built separately from the core (much like plugins are), but are bundled into the WAR file as a JAR file in WEB-INF/lib and therefore it behaves as if it’s a part of the core from the users' point of view. Modules can be thought of as something in between a library and a plugin. It has its own POM, a set of source code, and is built separately, like a library, but it gets the same compile-time processing as plugins do.

This assists splitting a big hair ball (that is the core) into more manageable smaller pieces, and allow OEMs to add/remove functionalities separately.

Each published plugin has its own page on https://plugins.jenkins.io/, such as this. These pages provide documentation and information about the plugin: installation statistics, changelogs, known issues, etc. Documentation is retrieved from the GitHub repository of the plugin or from an archived copy of the decommissioned Jenkins wiki. See the Plugin Documentation Page in the Developer guide for more information about how it works.

In the Jenkins core we roughly follow Sun coding convention in the source code, and we use 4 space indentation and don’t use tabs. It’s generally more practical and appreciated if you submit changes that don’t change the code format too much as it eases the coding review job. Try submitting formatting changes and functional changes in separate commits.

With that said, we do not believe in rigorously enforcing coding convention, and we don’t want to turn down contributions because their code format doesn’t match what we use. So consider this informational.

Jenkins plugins and other components may define their own code conventions.

See the pull request checklist for guidelines on submitting code to Jenkins.

When you have a license to do so, and when that license is compatible with the MIT license, you can copy the code from elsewhere into Jenkins.

The most typical case of this is that the original code is licensed under a certain subset of the open-source licenses, such as ASL, BSD, and MIT license. Copyleft licenses, even though they are open-sourced, cannot be copied, such as EPL and GPL. In particular, this means we can copy Oracle Hudson’s source code under the MIT license, but not Eclipse Hudson’s source code under EPL.

The code to be copied must be clearly marked with the license it is under, and when copying, you need to maintain the copyright/license attribution in the header. Please also indicate the origin of the copy as a part of the commit message.

Sometimes, it is necessary to make bug fixes and changes in the libraries that we use. Where the library is significant to Jenkins and the impact is considerable to our users, we choose to maintain local patch sets to upstream libraries, just like Linux distributions maintain such patches for its packages.

We normally intend such local patches to be integrated into upstream, so we file tickets upstream and provide our diff. When this works, this allows us to go back to the pristine upstream release at some point in the future. Those patch sets are maintained in our git repositories as a parallel branch.

In some cases, the supposed "temporary" patch sets became more permanent for various reasons beyond our control, such as the ceased development in the upstream, but that’s only because that’s how it turned out, not because we intended it at the outset. With the distributed version control system, maintaining parallel patch release for Jenkins isn’t as hard as it used to be.

If you develop a plugin, we encourage you to co-host that with the Jenkins project so that other people in the community can participate. See Hosting Plugins for more details.

If you are interested in just making a small number of changes without an intent to stay. It’s the easiest to send in pull requests through GitHub. See using pull requests for more details. If your pull requests are not getting timely attention, please ping us via the developers' mailing list, so that we can resolve that.

If you’d like to be involved more seriously, in addition to the pull request, we encourage you to consider becoming a committer. Drop us a note in the IRC channel or the dev list, and we’ll set you up with commit access. Try to be courteous to existing developers by sending them heads-up and coordinating with them, but if they aren’t responding, don’t let that block your progress. The seniority of the developers are earned through on-going participation.

It is often the case that the original developer moves onto other things once the plugin becomes good enough for them (or if the original author changes the job and no longer has incentive to work on the technology.) So we encourage new developers or developers of different plugin to pitch in on other plugins’ pending pull requests or work on issues filed against them.

To that end, we also encourage people to pick up dormant plugins and consider them theirs. See the Adopt a Plugin guidelines for more information.

Many less active plugins do not really have any obvious owner, and they are collaboratively maintained by people making small changes and releasing them whenever the need arises. If in doubt, ask on the dev list.

If you are interested in just making small changes, the same process applies as plugins. Just submit a pull request! However, because core changes affect a larger number of people, we’d be grateful if you’d try to go the extra distance on the notes described in using pull requests.

If you’d like to be involved more seriously in the Jenkins core, consider joining the Jenkins core maintainers team. See the onboarding guidelines here.

When making changes, use your common sense. For example, if you are thinking about making a big change, it is recommended that you discuss your changes with the developers upfront. Or if you see that the part you’d like to work on has been actively modified by others, give them a heads-up.

We are always looking for people who can help localize Jenkins to different languages. If you are interested in helping, drop us a note in the dev list to get commit access, and see Internationalization for the details of how to make changes.

As discussed above, Jenkins project uses pull requests as one of the main workflow to get the changes in. When you prepare your pull request, consider the following checklist as the best practice.

We do try to be attentive to inbound pull requests, unfortunately we may fail to review some of them in a timely fashion. If you notice that your pull requests aren’t getting attended to within a week or two, please drop us a note at the dev list or ping us in the GitHub pull request.