This is a work in progress. Feedback/comment/suggestion greatly appreciated
Who we are
Jenkins project as a community revolves around Jenkins as a 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 benefits.
The project is affiliated with Sofware in the Public Interest, a non-profit organization that provides legal representation and entity necessary to run an open-source software project. SPI also acts as our treasury, and legally owns the project assets.
Lower barrier of entry
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 of 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 different from the original author. We encourage new contributors to take over existing projects that aren’t actively maintained. We believe that “old” contributors deserve a respect from “new” contributors, but the inaction on the part of existing 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, records of the builds, plugin binaries that they are using. 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 the 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 free our time to do more creative work, but it also helps reduce the barrier of 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 is entirely in the MIT license, so are the most infrastructure code (that runs the project itself), and 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 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 ever making the source code available.
Contributor License Agreement (CLA)
To further clarify the intellectual property rights around the project, we require that core committers sign contributor agreement. This CLA is the same as Apache's CLA with "Apache" replaced to "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.
TODO: ~dty to prepare CLA texts and attach it here
CLAs come in two flavors. Everyone needs to sign Individual CLA (ICLA), and in cases where you as an individual do not own the work you are contributing (such as when your comapny assigns you to work on Jenkins and therefore your company owns the hard work you produced), the corporation also needs to sign Corporate CLA (CCLA). See the discussin in Apache for more details.
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 CLA for their work on plugins.
3rd party library licenses in the core
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 resouces can be spent elsewhere.
Jenkins as a whole needs to be open-source project, so we've been restricting ourselves to only use 3rd party libraries that are only OSI-approved open-source licenses (such as Apache Software License, BSD license, MIT license, Eclipse Public License, and Lesser GNU Public License.) In addition, we avoid so-called copyleft licenses that restrict the overall license to a specific license (such as GNU Public License.)
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.
3rd party library licenses in the plugins
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 it uses, 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 plugin on a non-GPL core.
The board consists of 3 people and they represent the project to outside when such representation is necessary, for example to interface with SPI.
Boards also acts as the ultimate decision making authority in case disputes cannot be resolved through the project meeting. The decision making ability of the boards is more symbolic and honorific, and it “rules” like British queens and not like dictators. Boards also interfaces with SPI and other external entities when some representation is needed.
Infrastructure administrators have the root access to the 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 the closed door. Infrastructure admins often appoint others to delegate some partial access to the system to complete some tasks.
Core committers are those who have the push access to the main Jenkins repository that produces
jenkins.war. To become a core committer, one needs to sign contributor license agreement. One is not required to have a proven history of contributions before granted the committership, but that doesn’t mean other core committers will never revert your changes.
TODO: we need to produce a list of core committers and make it visible somewhere publicly
Plugin committers are those who have the push access to the repositories that host plugins. One is not required to have a proven history of contributions before granted the committership. 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 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.
GitHub JenkinsCI organization is where we host most of our code today (see the list of repositories for easier navigation.) Because we traditionally 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 500+ Git repositories, some naming convention has 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 acess.
Our primary bug tracker is maintained by the infra admins. This uses the LDAP server described above for acess.
Jenkins on Jenkins
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.
Jenkins project uses bi-weeky project meeting as the primary forum of decision making for matters that need consensus. The meeting is open to anyone, and the minutes are public. Agenda items can be added by anyone by simply updating the Wiki page with your name.
The boards serve as the ultimate decision making body in case the project meeting fails to reach a consensus.
How we develop code
The core refers to a set of the code and libraries that produces
jenkins.war. The official core repository is 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 the commit access also use the pull request 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 made out of the release candidate (RC) branch, then a new RC branch is cut from the trunk. RC binaries are produced when the RC branch is cut, and it gets posted to the website for early adopters to try out.
Every 3 months or so we pick a past release as the long-term support (LTS) release and then branch off the ‘stable’ branch. This branch gets important bug fixes backported from the trunk and we’ll produce patch releases. See LTS Release Line for more details.
Core Coding Convention
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, 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 plugin 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.)
If you have trouble figuring out who to contact, the good fallback option is the dev list.
Plugin Wiki Page
Each plugin has its own Wiki page in
http://wiki.jenkins-ci.org/, such as this. Wiki page is expected to have the macro that produces the stock header table, and it describes what the plugin does, along with the release history / changelog. See other plugins for what they do for the guideline of what you should do.
These wiki pages are referenced from the update center, and they are the primary means users discover about your plugins.
Modules are libraries that are built separately from the core (much like plugins do), 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 the guideline of a commit.
Copying code from elsewhere
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.
Locally patching dependencies
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 prestine 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.
How to join the project
Bringing in new plugins/tools/libraries
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.
Making changes to existing plugins
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 request for more details. If your pull requests are not getting timely attention, please ping us at the dev 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 the 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.
Helping and taking over dormant plugins
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.
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.
Making changes to core
If you are interested in just making small changes without an intent to stay, the same process applies as the plugin, 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 involve more seriously, consider getting the committership. See the section about becoming a plugin developer for how to get the committership. In addition, we need to ask you to sign 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 a commit access, and see Internationalization for the details of how to make changes.
Using pull requests
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 check list 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 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 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.
- 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 fail to resolve some of them in timely fashion. If you notice that your pull requests aren’t getting attended in a week or two, please drop us a note at the dev list, and please consider becoming a committer and push the changes directly.
This document is owned and (to be) approved by the project meeting. Send your questions to the dev list.