Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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.

Our Philosophy

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. 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 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.

Meritocracy

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.

Transparency

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

Compatibility matters

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.

License

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.

Project structure

Boards

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 admins

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

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 CLA. 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

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

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

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.

Communication

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.

Mailing lists

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.

IRC

Jenkins project uses an IRC channel for real time interactive communications. This is also the place where active members bond with each other.

Twitter

@jenkinsci is the official twitter account of the Jenkins project, run by the infrastructure admins.

Decision making

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

Core

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.

Releases

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.

LTS Releases

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. However, 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

Plugins are developed autonomously by the people working on the plugin. Each gets its own repository, 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, new contributor shouldn’t worry too much about offending the culture by committing code. You can either try to contact existing developers upfront, or make a commit and accept the chance that they might revert that.

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.

Commit guideline

See the pull request checklist for the guideline of a commit.

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.

Contributing localizations

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.

  • No labels