The Jenkins project as a community revolves around Jenkins as a piece of software. We are a group of open-source developers and users who develop, use, promote Jenkins, software around Jenkins, and other related activities for our mutual benefit.
The project is affiliated with Software in the Public Interest (SPI), a non-profit organization that provides legal representation and other necessities for running an open-source software project. SPI also acts as our treasury, and legally owns the project assets.
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.
The Jenkins project uses the MIT License as the primary license of choice, for the code that we develop. Unless otherwise stated, all the code is under the MIT license.
The core of Jenkins is entirely under the MIT license, as is the majority of our infrastructure code (that runs the project itself), as well as many plugins. We encourage hosted plugins to use the same MIT license, to simplify the story for users, but plugins are free to choose their own licenses, so long as it’s an OSI-approved open-source license.
This is not to be confused with proprietary plugins --- we recognize and encourage plugins that people write on their own for their internal use, without necessarily making the source code available. But no such plugins will be hosted by the Jenkins project.
To further clarify the intellectual property rights around the project, we require that core committers sign a contributor agreement. This CLA is the same as Apache’s CLA with "Apache" replaced by "SPI". This agreement explicitly assigns a set of rights to SPI, such as the effective joint copyright ownership, patent grant, as well as acknowledging that you have the necessary rights to contribute changes.
The assignment of these rights to SPI helps Jenkins being neutral to any particular vendor, and it’ll also make legal departments happy especially in large organizations who want to use Jenkins.
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 from the following URLs:
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 OSI-approved open-source licenses (such as Apache Software License, BSD license, MIT license, Eclipse Public License, and Lesser GNU Public License.) 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:
CDDL, CPL, EPL, and MPL, and LGPL (these licenses require that derivative works to be under the same license as the original license, so the source code needs to be separated into its own repository, but binaries can be used as dependencies to the core.)
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 name "Jenkins" is a registered trademark in the USA (#4664929, held by Software in the Public Interest, Inc.) in order to protect the project and users from confusing use of the term. To reduce the process overhead and uphold our open-source spirit, we adopt the Linux kernel policy on trademark usage.
You need to apply for a sublicense if you are using the term "Jenkins" as part of your own trademark or brand identifier for Jenkins-based software goods or services. It doesn’t matter if your trademark is unregistered, or if you do not plan to make any money using the mark.
Answering the following questions (which break out each of the key issues) may help you determine if you need a sublicense. If you are still in doubt, please contact the board and we will work with you to determine whether you need to apply for a sublicense.
If the answer to all three of the following questions is "yes," then you need to apply for a sublicense. If the answer to any of these questions is "no," then you do not need to apply for a sublicense.
Is my mark a trademark (see how Linux Foundation define "trademark" in FAQ)?
Does my mark contain the following string of adjacent letters, in this order: "Jenkins"? These letters may or may not be capitalized, and in the case of foreign characters, phonetic translations also apply.
Do I use my mark to identify software-related goods or services (see how that phrase is defined again in LF)?
A list of trademark usages approved by the project can be found on the Approved Trademark Usage page.
These trademark attribution guidelines are largely derived from the Linux Foundation’s trademark attribution guidelines.
Even if your use of the Jenkins trademark doesn’t fall under the scope of the Jenkins Sublicense Agreement, you should still attribute ownership of the mark to Software in the Public Interest, Inc. in two ways:
For each web page, advertisement, or publication, the first prominent appearance of "Jenkins" should feature the "circle R" character adjacent to the "s", as follows:
At the end of your web page, advertisement, publication or media broadcast, include the following text in a legible font and size:
Jenkins® is a registered trademark of Software in the Public Interest, Inc.
The Jenkins Sublicense Agreement sets forth how the mark should be attributed by sublicensees. Sublicensees are required to place the following legend conspicuously on each piece of authorized goods, and at least once in the area of the title page of any documentation or sales literature accompanying each authorized good or service:
The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc.
The Jenkins project understands that space limitations can make including these attributions difficult. When made necessary by space limitations, any reasonable facsimile of these attributions may be used. In case of doubt as to the proper shortened form, examples may be submitted to the Jenkins project for approval.
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 queens 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 slaves 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.
A list of admins of some of the public infrastructure components can be found here: Infrastructure Admins
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.
The communication among people in the community is crucial to the oneness of the project. People in the Jenkins project communicates with each other in several different places.
We encourage mailing lists as the primary means of developer & user discussion, because of their asynchrony and ability to search the archive. The project website lists the active mailing lists and their purposes.
Jenkins project uses an IRC channel for real time interactive communications. This is also the place where active members bond with each other.
@jenkinsci is the official Twitter account of the Jenkins project, run by the infrastructure admins.
The GitHub JenkinsCI organization is where we host most of our code (see the list of repositories for easier navigation.) Because we previously used Subversion as the primary source code repository, we also have the subversion repository that contains all the original project history. Some plugins are still actively maintained inside the Subversion repository.
To aid classifying our 1000+ Git repositories, some naming conventions have been adopted:
plugins are named "*-plugin"
libraries are named "lib-*"
backend infrastructure programs are named "backend-*"
To encourage migration of plugins from Subversion to Git, a daemon is used to mirror plugins individually to GitHub. See this page for more about how to migrate your plugin to GitHub.
The infrastructure admins run an LDAP server and a small frontend program to let users create accounts on jenkins-ci.org. This account is used for all the software that we run ourselves.
This wiki that you are reading is our primary collaboration mechanism for documentation. This uses the LDAP server described above for access.
Our primary bug tracker is maintained by the infra admins. This uses the LDAP server described above for access.
We run Jenkins for our own development and to automate various infrastructure tasks. Because of the sensitive nature of setting up jobs, only the infra admins have full write access.
The Jenkins project uses biweekly project meetings as the primary forum of decision making for matters that need consensus. The meeting is conducted on IRC and open to anyone. Agenda items can be added by anyone by simply adding your topic to the Governance Meeting Agenda. Be sure to include your user name (so we know who proposed a topic).
The meeting minutes are public:
The board serves as the ultimate decision-making body in case the project meeting fails to reach a consensus on a particular topic.
The core refers to a set of code and libraries that result in the
jenkins.war binary. The official core repository is hosted on GitHub.
Long time committers push changes directly into this repository, although other core committers can still revert their changes and discuss them when they feel that is necessary. New committers can also do the same when they feel good about their changes, or if the changes are trivial.
Committers old and new who feel their changes need review use GitHub pull requests as a way to solicit feedback. People without commit access also use pull requests to get their changes into the core. Core committers are expected to be attentive to pending pull requests, and try to act on them quickly.
Core committers generally use their own judgement to decide what to work on.
Every weekend a new release is built from the master branch and released, in various forms, including
jenkins.war and native packages. This allows us to get new features and bug fixes into the hands of users relatively quickly.
Every three months or so we pick a prior release as the new long-term support (LTS) release and then create the ‘stable’ branch, from that release point. This branch gets important bug fixes backported from the master branch, and further patch releases are built roughly every two weeks until the next LTS baseline is chosen. See LTS Release Line for more details.
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.
Plugins are developed autonomously by the people working on the plugin. Each gets its own repository, its own Jenkins-on-Jenkins job, its own bug tracker component, and maintain their own release schedules.
Some plugins are actively maintained by a small number of people and they may have their own local culture, such as different coding convention, additional commit policies. We do this so that people can feel ownership and attachment to their effort, and so that they won’t feel like they have to follow externally decided rules.
Since much of such local culture is implicit, it’s often difficult to tell from outside the operating culture of a given plugin. The safe rule of thumb is to contact existing developers upfront before doing any commit (but if there’s no timely response in a week so, you should feel free to commit.) Less actively maintained plugins tend not to have such local culture, so in those cases, if you feel lucky you can commit changes ahead and send a heads-up simultaneously, (and accept the possibility that the changes get reverted.)
Maintainer information should be listed in the info box of the plugin’s wiki page. If you have trouble figuring out who to contact, the good fallback option is the developers' mailing list.
Each plugin has its own Wiki page in https://wiki.jenkins.io/, such as this. Plugin wiki pages should the macro that produces the stock header table, describing what the plugin does, along with the release history / changelog. Take a look at some plugin wiki pages as a guideline of what you should do.
These wiki pages are referenced from the update center built in to Jenkins, and they are the primary means through which users discover information about plugins.
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 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.
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.
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.
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.
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. To do this, drop us a note at the dev list, and try to contact the previous maintainer to find out if they are still interested in driving the plugin. Trying insistently to contact the latest apparently inactive maintainer(s) before taking over is is an important practice to us. The practice is generally to add them in CC on your maintainership requests to the dev ML.
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 without an intent to stay, the same process applies as plugins, described above. However, because core changes affect larger number of people, we’d be grateful if you’d try to go extra distance on the notes described in using pull requests.
If you’d like to be involved more seriously, consider getting commit access. See the section about becoming a plugin developer for how to get this. In addition, we need to ask you to sign the contributor license agreement (CLA).
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.
See the github online help for how to create a pull request
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 a permanent record on our system that 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 scripts to understand the history and generate changelogs without human help. If you use the notation
[FIX 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 tests.
Try to describe your changes so that other people understand what you did.
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 formats.)
We do try to be attentive to inbound pull requests, but as you can see here, unfortunately we can fail to resolve 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, and please consider becoming a committer and push the changes directly. See Pull Request to Repositories for more.
This document is owned by the community and substantial changes are approved via the project meeting. Send your questions to the dev list, or add an item to the next meeting’s agenda.