Development Resources/HOWTO/Starting A New Project
Before you start the process of creating a new project, consider whether or not it makes sense to create a component within an existing project instead.
- 1 Background
- 2 Overview of the Project Creation Process
- 3 After Creation
- 4 Ongoing Responsibilities
- 5 Reference Material
- 6 Licensing
- 7 Frequently Asked Questions
Code is very important at Eclipse. All Eclipse projects are expected to have code. But the responsibilities of an Eclipse project extend far beyond having code in an eclipse.org repository. Eclipse projects are responsible for developing a community of users, adopters, and contributors.
Before you bring your project over to Eclipse, you must have useful code and the beginnings of a community. Eclipse Labs provides a great place to host your project during this formative period. In fact, depending on the nature of your project, Eclipse Labs may be the right place to host your projects in perpetuity. If it is your intent to one day move the project to Eclipse, you should take the time to familiarize yourself with our processes to avoid surprises downstream (e.g. you should consider carefully tracking all contributions to the project).
Eclipse Development Process and Intellectual Property Policy
Eclipse projects are expected to take necessary precautions to mitigate the risk to adopters; a company that integrates the code from your Eclipse project, for example, does so with confidence that the code in your project can legally be distributed under the agreed-to terms. The processes that we have in place are designed to support this. Ensure that you are familiar with the Eclipse Development Process (EDP), Eclipse IP Policy, and IP Due Diligence Process.
The EDP is mostly about community involvement. An Eclipse project is considered successful only if a vibrant community develops around it. While the reviews and processes described by the EDP may seem onerous, they are a necessary part of community development. You should anticipate spending a significant amount of time responding to questions posed in various forums (Eclipse Forums, mailing lists, or even Stack Overflow). You should plan on attending conferences (especially Eclipse Summit Europe and EclipseCon), presenting webinars, writing papers, etc to support your project.
There is tremendous value in the Eclipse IP Policy, but that value comes at a cost. It is important that you understand what is involved. Code provenance tracking is critical (we need to know the source of all code that ends up in our repositories). To that end, all new projects are required to make an initial contribution before any code is committed to an Eclipse source code repository.
One implication of this requirement is that we assume that a new project starts from pre-existing code. Further, the initial contribution must be the first commit in the Eclipse Foundation-hosted repository. Existing history cannot be vetted by the IP team and cannot be included in the Eclipse repository. Projects that wish to host repositories on an approved external service (like GitHub) must obscure their existing history.
The Eclipse IP Team will review your initial contribution to ensure that the code can distributed through an eclipse.org property. In effect, we review to code to make sure that it hasn't been copied inappropriately, that licenses are being used correctly, and so forth. As part of this process, the IP Team will research the source of all code; depending on the size of your contribution, this can be a time-consuming process. Furthermore, any third-party libraries required by your code will have to be checked and approved by the IP Team. As an Eclipse project you are expected to maintain an IP Log containing (among other things) information about all contributions and third-party libraries; you are required to submit this log for review and approval as part of the release process.
A project cannot make a release until the due diligence on the IP contained in that release is complete. Please review the Initial Contribution page for more information.
The Eclipse Foundation holds the trademark for all Eclipse projects. Trademark assignment is undertaken prior to the creation of any new project. If you already have a trademark on your project name, that trademark must be assigned to the Eclipse Foundation. Be advised that trademark assignment can be a time-consuming process (it can take hours, days, or weeks depending on the circumstances surrounding the name).
Project Resources and Services
Open source projects at the Eclipse Foundation are required to make use of certain Eclipse Foundation services:
- All project issues must be tracked in the forge-specific Bugzilla instance (Eclipse, LocationTech, PolarSys);
- Source code must be maintained in a forge-specific Git/Gerrit instance (Eclipse, LocationTech,PolarSys) or a forge-specific GitHub organization (Eclipse, LocationTech, PolarSys);
- All third-party libraries used by the project must be tracked and approved for use by the Eclipse IP Team;
- Downloads must be distributed via a forge-specific downloads server;
- Developer (committer) communication must occur in the dev list provided to the project by the Eclipse; and
- Projects must keep their project metadata up-to-date.
Projects may optionally make use of user forum.
If so-desired, a project may host a website on Eclipse Foundation-hosted servers. Alternative hosting services for project-specific websites are not permitted. Websites not hosted by the Eclipse Foundation are considered third-party and so are subject to the Guidelines for Eclipse Logo & Trademarks (the Eclipse foundation asserts ownership of the project name trademark).
Use of Eclipse Foundation-provided and hosted build services is strongly recommended, but not strictly required. To be considered mature, it must be possible for members of the community to build project artifacts from source code.
Project artifacts (e.g. downloads) can be distributed via third-party services (e.g. Maven Central), but the Eclipse Foundation-provided infrastructure must be considered the primary source of project downloads. Where technically sensible, all downloadable artifacts must be signed by an Eclipse Foundation-provided certificate.
Projects that host source code on GitHub are not permitted to use GitHub Issues or Wiki.
Here are some other links that should help you with the process:
- Project Naming Policy - Selecting a name for your project;
- Pre-Proposal Phase - The whole process for proposing a project;
- Architecture Council - The role of the Architecture Council in a new project;
- Creation Reviews - Scheduling the proposal's creation review; and
- Incubation Phase - After the project has been created.
- Community Development - Communities don't develop themselves! Some of the things you need to think about.
This should sound like a lot of work. For many projects, the investment is worthwhile.
Overview of the Project Creation Process
- Use the online form (see Proposal Creation Links below) to create a proposal to assemble a proposal. Note that instructions are provided within the document.
- If you have any questions, please contact the EMO.
- The EMO will review the document and provide feedback. If there are timing issues with respect to "going public" let the EMO know (we can, for example, coordinate the public disclosure of the proposal with your marketing efforts).
- The EMO will post a draft copy and request your feedback on the "live" version. At the same time, the EMO will open a bug against Community/Proposals and Reviews to track the proposal.
- The proposal will be posted for community review
- It will appear on the "What's New" page.
- If necessary, the EMO will request mentors from the Architecture Council via Bugzilla.
- After we've posted the proposal, we need to let it sit for a minimum of two weeks to let the community review it. During that period, you should try to get as many people to look at the proposal and comment as possible. You should use this time to identify interested parties.
- The EMO will set a tentative date for the creation review
- The EMO will initiate a trademark search on the project name.
- The creation review cannot be started until after the trademark of the project name is secured
- It is difficult to estimate the amount of time required for a trademark search
- Your choice of project name and any existing trademark assertions on the name may increase the amount of time required (consider this when selecting your project's name)
- If you currently hold the trademark, you will be asked to complete a Trademark Transfer Agreement
- When both the community review period and the trademark search/assignment is complete, we'll finalize the date for the creation review, which will run for a one-week (Thursday to Wednesday) period.
- By this point, the review should really just be one more week for people to ask questions and comment.
- Creation reviews tend to always be successful (they should be considered low stress as the hard work has already been done).
- When the review is declared successful, you'll be invited to provide provisioning information
- the webmaster and IP team will use this information to provision space on our servers, create committer records, etc.
- When provisioning is complete, you can submit your initial contribution to the IP team for review
- The IP team must give you approval before anything can be committed to any Eclipse VCS or download server. Your mentors can help you at this stage.
- With IP Team approval, you can push your initial contribution to Git
- You're off to the races
- Projects must create a plan at the beginning of each development cycle
- Projects must engage in a release review for all major/minor releases
- Project committers are expected to abide by the terms of the Eclipse Development Process
Be sure to lean on your mentors for help, or for answers to questions. Make use of them, that's what they're there for.
Proposal Creation Links
The Eclipse Foundation runs multiple open source software forges. If you're not sure which forge to choose, pick Eclipse.
Create a new project proposal for:
Before you commit any code into your eclipse.org repository, you must submit your project's initial contribution for review by the IP team.
Community development is a big part of life at Eclipse. It is strongly recommended that you identify somebody on your team to be responsible for community development activities. To cultivate a vibrant community of users, adopters, and committers, a project has to have somebody who is responsible for community development. Somebody has to own it. Everybody on the project team has to dedicate some significant amount of their time to community development, but one person on the team has to be responsible for it. For some projects, this may be a full time job; for others, it may be a huge part of one. In fact, may open source projects have more than one full time person working on community development. In some circles, this role might be called the project's evangelist, or maybe it's the project lead that manages community development. Whatever the title, the role should be that of making everybody else successful in community development activities. Please see Community Development for Eclipse Projects.
Projects must maintain their metadata. This information is used to drive our automated processes. Kept up-to-date, project metadata can reduce your overall project maintenance burden by allowing our automated processes (e.g. project summary pages, project summaries, Dash data, etc.) to generate and disseminate correct information about your project.
Before an Eclipse project can release any software, they must undergo a release review. This is a well-defined formal process.
Projects in the incubation phase can only do pre-1.0 releases (e.g. 0.7). Before creating a >=1.0 release, a project must undergo a graduation review and enter the mature phase. A graduation review is typically combined with a release review. Note that a project may make 1.0 milestone releases (e.g. 1.0.0M1) in the time leading up to their graduation review. Note also that projects may select a >1.0 number for their first Eclipse release if that makes sense for the project and their community (you might consider this if your already-established project has moved to Eclipse).
If you have any questions, or are unsure of your responsibilities as a project lead or committer, please contact your project mentors or EMO.
Here are some valuable links:
If your project has special licensing requirements, you may need to make a presentation to the Eclipse board of directors to request their approval. The presentation need only briefly describe the project and why special licensing considerations are necessary.
Whether or not you require special consideration for project licenses is forge and top-level project-specific. As part of the project proposal period, we'll help you make sure that all the right things happen.
If you have questions regarding project licensing, please contact the Eclipse Management Organization (EMO).
Frequently Asked Questions
How do I find Architecture Council mentors?
- You don't have to find them yourself. Focus on the content of the proposal. We can solicit mentors from the Architecture Council after the proposal has been opened for community review.
Can I change the proposal after it is posted?
- Yes. The proposal can be changed any time before the start of the start of the creation review.
When do I submit my code for review by the IP team?
- Submit your code (initial contribution) for review after the project has been provisioned. The Eclipse Webmaster will let you know via email when provisioning is complete.
Does the new project have to use Git?
- Yes. Git is the only source code management system that is currently permitted for new projects. Some of our existing projects do use SVN, but that support has been deprecated and those project are encouraged to migrate to Git.
Can I host my project code on GitHub?
- New projects can make use of GitHub. Official project repositories must be moved under the appropriate Eclipse Foundation-owned GitHub organization (eclipse for Eclipse projects, locationtech for LocationTech projects, or polarsys for PolarSys projects). Official repositories are subject to the same intellectual property due diligence rules and processes that all Eclipse project repositories must follow.
- The Webmaster will create a copy (mirror) of GitHub-hosted repositories and maintain them on Eclipse Foundation hardware.
This page is moderated by the EMO.