Development Resources/New Commmitter Handbook
This page is intended for new Eclipse committers, and contributors who plan to become committers. Having said that, there should be a little something in here for everybody.
We are attempting to keep this page as concise as possible (using plain English), while conveying as much information as possible. This document is not the definitive source of information about being an Eclipse committer. It is just the starting point: it provides many links to more information.
As a committer, you must be familiar with the following documents:
The Eclipse Resources page is intended as a reference into the rest of the documentation. If you have a question, this is a good place to start. If you can't find the help you need there you should ask your project lead, or PMC.
We are continually trying to improve this page. If you think that something can be improved, or something should be added, please let us know by opening a bug against Community/Process. Or you can just edit this page: it is a wiki, afterall!
Several important principles provide a foundation for the Eclipse Development Process.
Eclipse Quality means extensible frameworks and exemplary tools developed in an open, inclusive, and predictable process involving the entire community. From the "consumption perspective," Eclipse Quality means good for users (exemplary tools - cool/compelling to use, indicative of what is possible) and ready for plug-in developers (deliver usable building blocks - with APIs). From the "creation perspective," Eclipse Quality means working with a transparent and open process, open and welcoming to participation from technical leaders, regardless of affiliation.
Copied from Eclipse Quality
Intellectual property (IP) is pretty much any artifact that is made available from an eclipse.org server (this includes source code management systems, the website, and the downloads server). Artifacts include (but are not limited to) such things as source code, images, XML and configuration files, documentation, and more; pretty much anything that a project makes available to the community in general. Fairly strict rules govern the way that we manage IP and your responsibilities as a committer (the links at the top of this page provide a lot more information).
Code produced by an Eclipse project is used by organizations to build products. These adopters of Eclipse technology need to have some assurance that the IP they're basing their products on is safe to use. "Safe" basically means that the organization or individuals who claim copyright of the code are the legitimate copyright holders, and the copyright holders legitimately agree to make the code available under the license(s) that the project works under. As a committer, you must be careful that you do not copy code and inadvertently claim it as your own.
A project is said to be transparent if the project team makes it easy for a member of the community, who is not part of the core team, to participate in all decisions that affect the project. The project should make it easy for a non-team member to find all the information used and the decisions made by the project team.
Copied from WTP Permeability and Transparency Checklist
A project is said to be permeable if the project team is receptive to new ideas from the community and welcomes new committers to its team. This is a measure of the 'responsiveness', 'friendliness' or 'sociability' of the project towards a participant who is not part of the project team.
Copied from WTP Permeability and Transparency Checklist
Top-level projects are defined in the Eclipse Development Process.
A Top-level project is effectively a container for projects that do the real work. A top-level project does not contain code. Rather, a top-level project contains other projects. Each top-level project defines a charter that, amoung other things defines a scope for the types of projects that it contains. Top-level projects are managed by a Project Management Committed (described below).
The Eclipse Development Process defines what it means to be a project at Eclipse.
Essentially, projects are where the real work happens. Each project has code, committers, and resources including a website, source code repositories, space on the build and download server, etc. Projects may act as a parent for one or more child projects. Each child project has its own identity, committers, and resource. Projects may, but do not necessarily, have a dedicated website (many projects share a website through their parent project). Projects are sometimes referred to as "subprojects" or as "components". The alternate terms are still used by some of our more seasoned committers, and in parts of our documentation. The Eclipse Development Process, however, treats the terms project, subproject, and component as equivalent.
Projects can be arbitrarily nested, forming a tree. The root of the tree is a single top-level project. In practice, project trees are never more than three levels deep.
There are numerous project-specific resources (including a list of all projects at Eclipse) on the Eclipse Projects Gateway page.
A committer is a software developer who has the necessary rights to write code into the project's source code repository. Committers are responsible for ensuring that all code that gets written into the project's source code repository is of sufficient quality. Further, they must ensure that all code written to an eclipse.org source code repository is clean from an intellectual property point of view. This is discussed with more detail below.
Contributions to an Eclipse project take many forms. As a committer, you should do everything possible to encourage contribution by members of the community that surrounds your project. Contributions take the form of code, input into your project's wiki pages, answering questions on newsgroups, and more.
Be aware that code contributions from outside of the project are best accepted through Bugzilla records. By attaching code to a Bugzilla record, the committer implicitly grants rights to use the code. Those contributions are subject to our IP policy.
Some of our documentation refers to contributors as "developers".
Project Management Committee (PMC)
Each top-level project is governed by a PMC. The PMC has one or more leads along with several members. The PMC has numerous responsibilities, including the ultimate approval of new committers, and approval of intellectual property contributions. Effectively, the PMC provides oversight for each of the projects that are part of the top-level project.
If you have a question that your project lead cannot answer, ask the PMC.
Project Lead (PL)
The project lead is more of a position of responsibility than one of power. The project lead is immediately responsible for the overall well-being of the project. They own and manage the project's development process, coordinate development, facilitate discussion amongst project committers, ensure that the Eclipse IP policy is being observed by the project and more. If you have questions about your project, the Eclipse Development Process, or anything else, ask your project lead.
Architecture Council Mentor
The Eclipse Architecture Council (AC) is a body of battle-hardened Eclipse committers. All new projects are required to have a minimum of two mentors taken from the ranks of the AC. Your project mentors will help you find answers to any questions you may have about the Eclipse Development Process and life-in-general within the Eclipse community. If your mentor doesn't have an answer to your question, they can draw on the wisdom of the full AC and the EMO.
Eclipse Management Organization (EMO)
In the strictest sense, the EMO consists of the Eclipse Foundation staff and the Councils (Requirements, Architecture, and Planning). The EMO is responsible for providing services to the projects, facilitating project reviews, resolving issues, and more. The EMO is the maintainer of the Eclipse Development Process.
The main point of contact with the EMO is by email at email@example.com. If you have a question that cannot be answered by project lead, mentor, or PMC, ask the EMO.
Executive Director (EMO/ED)
The Executive Director (EMO/ED) is the head-honcho at the Eclipse Foundation. He is ultimately responsible for all the goings-on at the Eclipse Foundation.
Contribution Questionnaire (CQ)
Prior to committing a significant contribution of content to an Eclipse Foundation project, the committer must fill out a contribution questionnaire and submit it to the Eclipse Management Organization (EMO) for approval. In addition to the EMO, the relevant PMC must also provide a technical review and approval of the contribution.
In general, ongoing development by project committers does not require EMO or PMC approval. When in doubt, consult the Eclipse IP Due Diligence Process.
Now this is a tough one. For most people in the broader community, "Eclipse" refers to a Java IDE based on the JDT project and assembled by the Eclipse Packaging Project. However, the term "Eclipse" is also used to refer to the Eclipse Foundation, the eclipse.org website, the community, the eco-system, and—of course—The Eclipse Project (which is just one of the top-level projects hosted by the Eclipse Foundation). Confusing?
Community is a nebulous sort of term. Community is the group of individuals and organizations that gather around your project. In the case of some projects, like the Eclipse Project, the community is enormous. Other projects (most, frankly) have smaller communities. Developing a community is a very important part of being an Eclipse project as it is from the community that you get feedback, contributions, fresh ideas, and ultimately new committers to help you implement your shared vision.
The "Eclipse Community" is formed from the union of the communities that grow around individual projects.
A commercial ecosystem is a system in which companies, organizations, and individuals all work together for mutual benefit. There already exists a vast ecosystem of companies that base significant parts of their business on Eclipse technology. This takes the form of including Eclipse code in products, providing support, and other services. You become part of an eco-system by filling the needs of commercial interests, being open and transparent, and being responsive to feedback.
Ultimately, being part of a commercial ecosystem is a great way to ensure the longevity of your project: companies that build their business around your project are very motivated to contribute to your project.
Lower the Barriers
This section is heavily based on a mailing list posting by Pascal Rapicault.
One of the most critical aspects of running an open source project is to "lower the barrier of entry" for both contributors and users.
- Make it easy for people to find the starting point. Where is the code, how to build it, running the tests, etc.
- Make the contribution process clear. How to contribute patches (patch attached, gerrit, ...), etc.
- Make the schedule clear. Build schedule, delivery schedule, etc.
- Take the important decision in the open. Of course this is not about having every single chit/chat to be captured on the mailing list or a bug report (after all you don't want to sacrifice the efficiency of your tightly knit team) but rather make sure that decisions and the reasoning are captured somewhere (for example, always make sure that the final resolution and the whys are captured in a bug report so people cab interject).
- Schedule team meeting phone calls. Consider implementing a weekly phone call where you can discuss the schedule, the on-going work, and also the more complex/controversial technical things which would have not been easy to take care of by email.
- Concise and clear description of the project on the website.
- A five min tutorial is of great use and help captures the audience.
- Where to go to ask question (consider using a forum or a separate mailing list for this)
- Great documentation, with a lot of ready-to-go examples.
My Foundation Portal
The My Foundation Portal is the primary mechanism for committers to interact with the Eclipse Foundation. Using the portal, you can update your personal information, nominate new committers, and more. The portal presents functionality in the form of individual components. The set of components depends on the roles assigned to you.
Note that the portal has been deprecated and that we are moving functionality directly onto the website in the form of what we're calling the Project Management Infrastructure.
You can use either your Eclipse Bugzilla or your committer credentials to login. Some committer-specific functionality is only available when you login using your committer credentials.
Licenses, Intellectual Property Due Diligence, and other Legal Stuff
The Eclipse Legal page is the main resource for legal matters. Janet Campbell, Legal Counsel & Intellectual Property Team Manager for the Eclipse Foundation, presented a talk, IP for Eclipse Committers, at EclipseCon 2009 that provides a great overview of the IP policy and process at Eclipse.
As an Eclipse Committer, you should be familiar with the Eclipse Public License (EPL). Further, you should be aware of the Eclipse Distribution License (EDL). By default all code authored for an Eclipse project is subject to the EPL. The BSD-style EDL license is used by some Eclipse projects which require dual-licensing along with the EPL. Use of this license by an Eclipse project is on a case-by-case basis and requires unanimous approval of the Board of Directors.
Managing intellectual property is an important part of being an Eclipse Committer. All committers should be familiar with the Intellectual Property Due Diligence process. Any time you accept code from any party (committer or non-committer), you should consult this poster to determine what course of action to take. As a general rule, code created on an ongoing basis by committers for an Eclipse project can simply be committed into the project's source code repository.
All Eclipse projects start with an initial contribution of code. Some contributions are big, other are small. Whatever the case, the IP Team needs to review your first drop of code before anything gets added to the repository.
You need a contribution questionnaire (CQ) for a third-party library if you make direct use of that library. An import statement in Java source, or a bundle reference or package reference in a manifest file are examples of a direct reference. Indirect references through another project's code do not generally require a CQ.
The entry-point into the Eclipse IP Due Diligence Process is the Contribution Questionnaire (CQ). CQs are tracked in a separate Bugzilla instance known as IPZilla. Only committers and other authorized individuals may access IPZilla.
You should create a CQ using the My Foundation Portal. By using the portal, you are given an opportunity to locate similar existing CQs; by leveraging an existing CQ, you may be able to hasten the approval process. The CQ describes the contribution, including important information like the license under which it is distributed and identity of the various authors. Once your CQ is created, you must attach the source code for the library to the record. Do not attach binaries. A separate CQ is required for each library.
Do not commit any contribution to your project's source code repository until the CQ is explicitly marked as approved and a comment is added by the IP Due Diligence Team that explicitly states that you can commit the contribution.
An incubating project may make use of the Parallel IP Process. Using the Parallel IP Process, a contribution can be committed into a project's source code repository while the due diligence process is undertaken. If, at the end of the due diligence process, the contribution is rejected, it must be removed from the source code repository. The Parallel IP Process "How to" page provides some insight. Mature projects can take advantage of the parallel IP process for certain libraries.
Projects are encouraged, where possible, to reuse libraries found in the Orbit project. Leveraging these libraries will help to reduce redundancy across Eclipse projects.
If you are unsure about what you need to do or have other questions, ask your PMC.
How do I get Help?
Projects have at least one mailing list. The mailing list is a good place for developers on a project to ask questions of other developers. That is, the mailing list is typically intended for communication amongst developers on a project. Your project's home page should provide some help in identifying the mailing list. Alternatively, you can find the comprehensive list of all mailing lists here.
Your project teammates are probably your best source of pertinent information. If you are working on an incubating project (i.e. a project that has not yet done a 1.0 release), there should be mentors assigned to your project to help with questions. Don't be afraid to use your mentors. You can identify the mentors on the project summary page (which should be accessible in an entry labeled "About this Project" in the left-menu on your project's web site).
For communication with another project, you should go through the community Forums. If you're not sure which forum to post your question on, try posting on the newcomer group and someone there will point you in the right direction. Note that the forums are also available through NNTP if you prefer to use a newsreader.
This page is moderated by the EMO