LocationTech Project Handbook

LocationTech Project Handbook

Notices

Copyright © 2015, 2016 Eclipse Foundation, Inc., Made available under the Eclipse Public License v 1.0

Overview

This document provides you with the information that you need to create a new LocationTech open source project or become a committer on an existing one.

While this document is focused on LocationTech, it makes several "Eclipse" references, including the Eclipse Foundation, Eclipse Development Process, and Eclipse Management Organization. The Eclipse Foundation is the legal entity that manages the operations of the LocationTech working group, software development forge, and community. Many of the provided services and contacts are so-named on that basis.

The Eclipse Development Process (EDP) is the foundational document for LocationTech projects and committers. It describes the manner in which we do open source software. The Eclipse Development Process does not prescribe any particular development methodology; it is more concerned with the larger-scale aspects of open source project lifecycle, including such things as reviews, processes for running votes and elections, bringing new committers onto a project, etc. This document will elaborate on some key points of the Eclipse Development Process.

Principles

Four basic principles lie at the heart of the Eclipse Development Process:

  • Transparency;

  • Openness;

  • Meritocracy; and

  • Vendor neutrality

We refer to the first three as the "open source rules of engagement".

To operate with transparency, a project’s discussions, minutes, deliberations, project plans, plans for new features, and other artifacts are open, public, and easily accessible.

Openness at LocationTech means quite a lot more than "open book" (which is really a synonym for transparent). The project is open to all; LocationTech provides the same opportunity to all. Everyone participates with the same rules; there are no rules to exclude any potential contributors which include, of course, direct competitors in the marketplace.

LocationTech is a meritocracy. The more that somebody contributes, the more responsibility they will earn. A pattern of quality contribution to a project may lead to an invitation to join the project as a committer. Leadership roles in LocationTech are also merit-based and earned by peer acclaim. Merit must be demonstrated in publicly-accessible forums. Committers and project leads are added to a project via election.

Note Employment status has no bearing at whether or not somebody can participate in an open source project at LocationTech. Employment does not guarantee committer status; committer status must be earned by everybody.

Vendor neutrality is similar to openness in that it’s concerned with maintaining a level playing field. No vendor is permitted to dominate a project, and nobody can be excluded from participating in a project based on their employment status. While project resources will contain copyright statements that assert ownership of various assets by individual vendors, the project itself must remain vendor neutral.

Quality and intellectual property cleanliness are also important principles.

Quality means extensible frameworks and exemplary tools developed in an open, inclusive, and predictable process involving the entire community. From the consumption perspective, LocationTech quality means good for users (exemplary tools are cool/compelling to use, indicative of what is possible) and ready for use by adopters. From the creation perspective, LocationTech quality means working with a transparent and open process, open and welcoming to participation from technical leaders, regardless of affiliation.

Intellectual property (IP) is any artifact that is made available from a LocationTech 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. Strict rules govern the way that we manage IP and your responsibilities as a committer.

Code produced by an LocationTech project is used by organizations to build products. These adopters of LocationTech technology need to have some assurance that the IP they’re basing their products on is clean: 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.

Starting an Open Source Project at LocationTech

Before getting started, it’s important to know what is required of a LocationTech project. The Eclipse Foundation will take ownership of many aspects of the project to ensure that the project and its assets are are managed in an open and vendor-neutral manner. This takes the form, for example, of the Eclipse Foundation retaining ownership of project’s trademarks on behalf of the community, and carefully managing who has write access on project resources such as source code repositories and distribution channels. LocationTech projects are obligated to use certain resources assigned to the project by the Eclipse Foundation and conform to logo and trademark guidelines. New project sponsors must engage in the process of transitioning an existing project with the intent to continue development of the project code and growth of the community and ecosystem around the project.

It’s also important to know what new projects don’t give up. The project team retains control of the project’s direction by virtue of regular contribution to the project. The contributors to the project retain ownership of their contributions (those contributions are used under license by the project). Project leads are required to ensure that other individuals who present themselves to the project are given uniform opportunity to participate, but project team gets to establish the rules for participation (within certain parameters). The project team is responsible for determining development methodology, establishing plans, etc. Existing owners of the project code retain their ownership.

LocationTech open source projects start with a proposal that is made available to the community for review. At the end of the community review period, we engage in a creation review, and then provision the project resources.

An overview of the Project Creation Process
Figure 1. An overview of the Project Creation Process

Use the web form to create a new project proposal. Instructions are provided on the form. All new proposals are created in draft mode, and are accessible only by the original author and anybody designated as a project lead or committer in the proposal. Only those individuals designated as a project lead may edit the proposal.

Note Keep track of the URL of the proposal. We do not provide public links to the document until after the proposal is opened for community review.

A proposal must minimally include a description of the project, a declaration of scope, and a list of prospective members (project leads and committers) before we make it accessible to the public for community review.

When you feel that the proposal is ready, send a note to the Eclipse Management Organization (EMO) at emo@eclipse.org requesting that the proposal be made available to the public for review. The EMO will review the proposal and may provide feedback before initiating the community review period.

At the beginning of the community review period, the EMO will announce the proposal on several channels (the Project Activity News page, Twitter, the Proposals Forum, blog post, and an email note to the Eclipse Foundation members and committers). The EMO will also open an record in the Eclipse Foundation’s issue tracker—​an instance of Bugzilla—​to track the progress of the proposal; the proposal’s author and project leads will be copied on that record.

A proposal will be open for community review for a minimum of two weeks.

The Eclipse Foundation holds the trademark for all LocationTech 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). If you currently hold the trademark, you will be asked to complete a Trademark Transfer Agreement.

The proposal must list at least one mentor from the Architecture Council. Members of the Architecture Council have considerable experience with Eclipse Foundation practices, and the Eclipse Development Process. If you are already in contact with mentors who agree to help you with your project, please do list them in the proposal. Otherwise, the EMO will engage directly with the Architecture Council to identify mentors as necessary. Mentors are available to the project through the incubation phase; they are released from their duties when the project graduates.

When the project name trademark has been secured, a mentor has been identified, and the proposal contents are finalized, the EMO will schedule a creation review. Reviews—​which run for a minimum of one week—​are scheduled twice a month, generally concluding on the first and third Wednesday of each month. The creation review may overlap with the community review period.

Note Creation reviews tend to always be successful. They should be considered low stress as the hard work has already been done in advance of the start of the review.

Following the creation review, the EMO will initiate the provisioning process. To gain committer status, some committer paperwork must be completed as part of the provisioning process. The exact nature of that paperwork depends on several factors, including the employment status of the individual and the Eclipse Foundation membership status of their employer.

Note If you can be ready with the paperwork in time for the completion of the creation review, then we can move quickly through the provisioning process. When we initiate provisioning, committers will be sent an email with instructions; please don’t send any paperwork in until after you receive those instructions.

After Provisioning

The Webmaster will send a note announcing the completion of the provisioning process. Before you commit any code into your project repository, you must submit your project’s initial contribution and list of third-party libraries for review by the IP team.

Post creation activities
Figure 2. Post creation activities

Do not commit any code to your project’s source code repository until after you receive approval for the IP Team. Once you’ve received that approval, you can do builds and produce milestones for your first release. You must wait until after the IP Team has approved your initial contribution and use of third-party libraries before you do any official releases.

Project Phases

All new projects start in the incubation phase (a project in the incubation phase is said to be incubating). The classification of a project in the incubation phase is not a statement about the quality of the project’s code; rather, incubation phase is more about the project team’s progress in practicing the open and public processes necessary to establish the three communities (developers, adopters, and users) around the project.

Egg incubation
Figure 3. The Incubation Logo

In order to alert potential consumers of the incubating nature, projects in the incubation phase must include incubation branding. The project team must:

  • Display the incubation logo on their project web page (if they have one);

  • Display the incubation logo on their project’s primary download page;

  • Include the word "incubation" in the filename of all downloadable files (when technically feasible) for builds and milestones;

  • When technically feasible, include the word "incubation" in features (e.g. about dialogs, feature lists, and installers).

There are no incubation branding requirements for general user interface elements.

Note For projects that produce OSGi artifacts, include the word "incubation" in the Bundle-Name, feature names, and p2 repositories. The word "incubation" should not be included in technical namespaces (especially when it may result in confusion when the project leaves incubation). e.g. an OSGi bundle’s Bundle-SymbolicName, or a Java package name.

Incubating projects that correctly conform to the incubation branding rules outlined above may take advantage of the Parallel IP Process. They are encouraged to produce milestone builds, make releases, and grow their community.

When the project code is ready (e.g. stable APIs) and the project team has learned to operate as an open source project according to the Eclipse Development Process, the project may opt to graduate into the mature phase.

Most of the lifetime of a LocationTech project is spent in the mature phase. A mature project is one that:

  • Is a good open source citizen with open, transparent, and meritocractic behavior;

  • Regularly and predictably releases IP clean extensible frameworks and exemplary tools; and

  • Actively nurtures the three communities: developers, adopters, and users.

Frequently Asked Questions

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

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

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

  4. Does the new project have to use Git?

    Yes. Git is the only source code management system that is currently permitted for new projects.

  5. Can I host my project code on GitHub?

    New projects can make use of GitHub. Official project repositories must be moved under the LocationTech Organization at GitHub. Official repositories are subject to the same intellectual property due diligence rules and processes that all Eclipse project repositories must follow.

  6. How long should I let my project incubate?

    It depends. Community expectations are one factor. Team experience with open source is another. If your team is new to open source, it may make sense to stay in incubation a little longer than a seasoned team with a mature code base might. As a general rule, though, projects should plan to leave incubation within a year.

  7. Does the mature project code that I’m bring to LocationTech need to incubate?

    Yes. All new projects start in the incubation phase. Remember that incubation is as much about the project team learning about how to operate as an open source project as it is about the project code. Project teams that "get it" can opt to exit incubation quickly (e.g. with their first release) if that makes sense for the team and the community.

  8. What do all these terms (e.g. EMO) mean?

    Please see the glossary.

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 a the issue tracker assigned to the project;

  • Source code must be maintained in source code repositories assigned to the project (e.g. a LocationTech Git or Gerrit instance, or the LocationTech Organization on GitHub);

  • 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 Foundation; and

  • Projects must keep their Project Metadata up-to-date.

Source Code Management

Your project must maintain source code in the repositories assigned to the project by the Eclipse Foundation. These official repositories must be the exclusive source of all project code delivered via the project’s assigned distribution channel (e.g. the download server).

In order for your project to operate in an open manner, it must be possible for potential contributors to have access to the code base in its most current form, so all ongoing development must be regularly pushed to these canonical repositories.

Contributor License Agreement (CLA)

The Eclipse Foundation has implemented Contributor License Agreements (CLA) to improve intellectual property (IP) management and workflow. All contributors, who are not committers on the LocationTech project, must sign the CLA.

You do not require a CLA to contribute to a project on which you have committer status.

Git Commit Records

Git commit records are required to take a specific form. The credentials of the actual author must be used to populate the Author field. The email address used must match the email address that the Eclipse Foundation has on file for the author (case-sensitive).

The commit message is divided into three sections:

  1. One line (max 72 characters) summary;

  2. Description; and

  3. Footer.

Example Git Commit Record
commit d6cf52411377a039fc2906378711091a26e932cb
Author: Some Body <somebody@somewhere.com> 1
Date:   Wed May 29 16:17:36 2013 +0200

    Bug 350686 - Hide unwanted action bar items 2

    This change hides unwanted 'Link with Editor' and
    'Customize View...' items from the local toolbar
    and the view menu.

    Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7 3
    Also-by: Some Bodyelse <somebodyelse@nowhere.com> 4
    Signed-off-by: Some Body <somebody@somewhere.com> 5
1 The email address of the author must match the email address on the Eclipse Foundation account.
2 Best practice: include the bug id in the commit message summary.
3 Gerrit change id (only when pushing to Gerrit for review).
4 Additional authors can be added using Also-by entries.
5 Non-committers must sign-off the commit using the same email address as used in the author field.

The summary line is used in many places where Git commits are listed, ensure that this line is sensible by itself. The description area should be used to provide more detail about the commit. The footer area is used for extra fields and values.

If the bug id is included in the summary line (using the form "Bug 12345 - xxx" or "[12345] xxx") Gerrit Code Review will automatically add a link in the corresponding Bugzilla record back to the Gerrit record (this, of course, only applies to commits pushed to Gerrit).

The Change-Id is used by Gerrit Code Review to associate new versions of a change back to its original review. This field need only be specified if the repository is managed by Gerrit.

Create a separate Also-by field for each additional author of a commit. This might apply, for example, if a commit has been authored via pair-programming, or the commit is the result of collapsing multiple commits authored by multiple developers.

Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Contributor License Agreement (CLA) on file.

Git

Those projects that want to use Git on the LocationTech forge, are assigned a directory in which they may create as many Git repositories as required. Open a bug to request that the Webmaster create a new Git repository for your project. Alternatively, committers with shell accounts can create repositories themselves.

Create a new Git repository
> initrepo /gitroot/project/org.locationtech.repo.name.git

For consistency, the name of the repository must end with .git.

To set the description of the repository, use sftp or scp to copy a text file to /gitroot/project/org.locationtech.repo.name.git/description. Git repository descriptions should be limited to a paragraph of one or two sentences.

Only project committers can push to a LocationTech Git repository. A push that includes commits that do not conform to the required form will be rejected.

You can browse LocationTech repositories directly on the Git server.

Gerrit Code Review

Gerrit provides web based code review and repository management for the Git version control system. Many projects use Gerrit to reduce barriers and encourage contribution to the project. Open a bug to request that the Webmaster configure your Git repository for Gerrit.

Commits may be pushed directly to the Git repository through Gerrit by a project committer (e.g. to the master branch).

Anybody can push to a refs/for/* branch for review in a Gerrit repository. A push that includes commits that do not conform to the required form will be rejected. Commits intended for review should have a Change-Id

You can browse LocationTech repositories directly on the Gerrit server.

GitHub

Projects may opt to move some or all of their canonical source code repositories to the LocationTech organization on GitHub. Both GitHub Issues and Wiki may also be used.

Open a bug to request that the Webmaster create a new, or move an existing, Git repository for your project. The Webmaster will install some hooks on your GitHub repository.

The Committers hook grants designated project committers write access to the GitHub-hosted project repositories. Project committers must use the email address they provide to the Eclipse Foundation as their GitHub email address.

The Contributor License Agreement (CLA) hook will inspect incoming GitHub pull requests to ensure that the contributor has a valid CLA on file, and that the commit has been "signed-off" as required. Project committers should only merge pull green requests:

Github cla success
Figure 4. Notification that the commit is properly structured and permissions are in place.

The GitHub API does not give us a means of absolutely denying a merge; all we can do is warn you that the contributors have not signed a CLA:

Github cla failure
Figure 5. Notification that there is something wrong with the commit.

Do not merge unless you are absolutely certain that the contributer does have a valid CLA on file (e.g. the Contributor License Agreement Lookup Tool confirms that they have a CLA).

You must manually check that the commit message includes the required "Signed-off-by" statement in the footer.

The Webmaster creates and maintains a mirror of all GitHub-hosted repositories on Eclipse Foundation hardware.

Issue Trackers

LocationTech projects must use an Eclipse Foundation-provided issue tracker. Project teams may opt to use either the LocationTech Bugzilla instance or—​for projects that use GitHub--GitHub Issues instances associated with Eclipse Foundation-managed GitHub project repositories.

Note Per directive from the Eclipse Foundation’s Board of Directors, you must obtain approval from your PMC to use GitHub Issues.

To request GitHub Issues access for your project, a bug against Community/GitHub and send the link to your PMC’s mailing list with a request for their approval.

Third-party Libraries

LocationTech projects must register all of their third-party library use with the IP Team.

Forums and Outbound Communication

All projects are assigned a user forum as a point of contact between the user and adopter communities, and the project developers.

The EMO strongly encourages the use of alternative communication channels for connecting with the community: your project team knows your community and how to best connect with them.

Project Websites

Project websites are an excellent way to connect your project with your community. Many projects opt to use the Project Management Infrastructure (PMI) as their project website, but if so-desired, a project may host a website on Eclipse Foundation-hosted servers.

Project website sources are hosted in Git repositories maintained by the Eclipse Foundation. Open a bug to request that the Webmaster create a website for your project.

Note Alternative hosting services for project-specific websites are not permitted. Websites not hosted by the Eclipse Foundation are considered community portals and so are subject to the Guidelines for Eclipse Logo & Trademarks (the Eclipse Foundation asserts ownership of the project name trademark).

Builds

Use of Eclipse Foundation-provided and hosted build services, the so-called Common Build Infrastructure (CBI) is strongly recommended, but n ot strictly required.

Whether or not your project chooses to make use of provided build resources, it must be possible for members of the community to build project artifacts from source code with reasonable effort.

Signed Artifacts

Where technically sensible, all downloadable artifacts should be signed by an Eclipse Foundation-provided certificate.

Downloads

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.

Project committers can upload project artifacts to the project’s directory on the download server.

Frequently Asked Questions

  1. Can a project use the gh-pages support from Github to host at <project>.github.io?

    The project’s primary website must be hosted on Eclipse Foundation infrastructure. GitHub’s gh-pages support can be used to host supplementary content only as a Community Portal (and is subject to the branding requirements).

Elections

Roles in a project are assigned based on merit demonstrated in a publicly-accessible forum, in the form of an election. Elections start with a nomination that contains a statement of merit. The nature of a statement of merit varies widely, but is generally expected to to concisely state the impact that the nominee has had on the project.

Note Employment status has no bearing at whether or not somebody can participate in an open source project at LocationTech. Employment does not, for example, guarantee committer status; committer status must be earned by everybody.

Committer Elections

Contributors who have the trust of the project’s committers can, through election, be promoted to committer status for that project. The breadth of a committer’s influence corresponds to the breadth of their contribution. A development team’s contributors and committers may (and should) come from a diverse set of organizations. A committer gains voting rights allowing them to affect the future of the project. Becoming a committer is a privilege that is earned by contributing and showing discipline and good judgment. It is a responsibility that should be neither given nor taken lightly, nor is it a right based on employment by an Eclipse Foundation member company or any company employing existing committers.

Being a LocationTech Committer is more than just having write-access to the project resources: there are specific IP due diligence and record keeping activities that Committers must follow. New committers must ensure that they are familiar with the Committer Guidelines.

New committers should be encouraged to join the Incubation Mailing List; this list is a good place to ask questions about process, services available, and other aspects of working as a committer.

What are the Requirements?

There are only three requirements around nominating and electing new committers (note that there are additional Committer Paperwork requirements for the new committer):

  • Define Trust. Each project is entitled to define how it evaluates "[people] who have the trust of the Project’s Committers …​ [through] contributing and showing discipline and good judgment". This definition needs to be a transparent and public document on the project’s website (the top-level project charter may provide this). It is extremely important to publish these criteria to avoid any issues around cliques or "the in-crowd" preventing others from joining a project.

  • Employment Neutral. There must not be any hint of "we (company W) hired person X to work on project Y thus person X should elected a committer". Committer status is independent of employment; there are well-supported mechanisms for contributors without commit-rights and thus Committer status is not required for a team member to be effective. Additionally, the team will want to make sure that they have confidence in the candidate irrespective of employment and management because the committer status will continue even after moves to another job.

  • Public and Archival Election. The nomination and election process for a new Committer is for more than just the project team - it is also for the entire LocationTech community, current and future. The larger community uses the artifacts of elections as (one of many pieces of) evidence about the maturity of the project team, and thus quality of the frameworks.

Note Nominations such as "we all know Bob, vote for him" may work within the team, but actually harm the project’s reputation in the larger LocationTech community: that larger community does not know Bob and does not understand why the project team trusts him with the source code.

What Should a Nomination Look Like?

A committer nomination should explain the candidate’s contributions to the project and thus why they should be elected as a Committer. Cite the issues they have fixed via patches; cite the community forum postings they have answered; cite the dev list design discussions to which they have contributed; etc. In all cases, provide urls to source material.

How does an Election work?

Use the developer portal to elect a committer.

  • Log in and navigate to the Eclipse Projects section;

  • Expand your project by clicking the [view] link on the right;

  • Click [nominate] a new committer for <project>; and

  • Follow the workflow.

Project committers will be notified to participate in the election via the project’s dev list.

Note Your project must have a dev list specified in the project’s metadata and existing project team members must be subscribed to the list.

An election starts with a nomination by an existing committer.

An overview of the Election Process
Figure 6. An overview of the Election Process

Only project committers may vote in a committer election. To be successful, the election must receive a minimum of three positive +1 votes. Any committer can veto the election by casting a -1 vote. For projects with three or fewer committers all committers must vote. Committer elections run for one week, but will end prematurely if all project committers vote +1.

Following a successful committer vote, the project’s PMC will review the election results and then either approve or veto the election. An election may be vetoed, for example, if the PMC feels that the merit statement is not strong enough.

The paperwork process will automatically be initiated following PMC approval of an election.

Project Lead Elections

Similar to a committer election, a project lead election starts with a statement of merit. The merit statement should, rather than focus on specific code contributions, focus instad on the leadership qualities expressed by the individual.

Example 1. Project Lead merit statement

Sounak has been part of the Ogee development since before the initial contribution. He played an important role ever since, as he is one of the key developers. With regards to the number of commits Sounak is currently the top committer of Ogee: http://git.eclipse.org/c/ogee/org.eclipse.ogee.git/stats/?period=q&ofs=10 Apart from that Sounak took care of the project page and the build. For release 0.6 he also handled the review formalities for me. Finally I would like to mention a blog post he did at odata.org to promote Ogee in the OData community: http://www.odata.org/blog/eclipse-ogee

Project leads are normally also committers. A project may have more than one project lead (so-called co-leads).

Use the Nominate a Project Lead link in the Committer Tools block on the project’s management page to start a project lead election.

Only project committers can vote in a project lead election. To be successful, a project lead election must receive a minimum of three positive +1 votes. Any committer can veto the election by casting a -1 vote. For projects with three or fewer committers all committers must vote. Committer elections run for one week, but will end prematurely if all project committers vote +1.

Following a successful committer vote, the project’s PMC will review the election results and then either approve or veto the election. A PMC-approved election will be referred to the EMO/ED as a recommendation for appointment. The final decision rests with the EMO/ED.

PMC Member Elections

The manner in which a top-level project’s Project Management Committee (PMC) Member is appointed varies by PMC. Some PMCs are set up to have a representative from each of the projects in the top-level project. Other PMCs are more exclusive and run an election similar to that of a project lead election.

In all cases, the PMC Lead makes a recommendation to the EMO/ED to appoint a PMC Member. The final decision rests with the EMO/ED.

PMC Lead Appointments

PMC Leads are are not elected. They are vetted by the EMO, approved by the Eclipse Board of Directors, and appointed by the EMO/ED.

Frequently Asked Questions

  1. Do we really need to do this?

    Yes.

  2. Can I still be a committer if I change employers?

    Yes. Your status as a committer is not tied to your employment status. You may, however, require Committer Paperwork from your new employer (or if you become self-employed). If you change employers, please contact emo-records@eclipse.org for help regarding paperwork requirements.

  3. What happens if committers don’t vote?

    If a project has three or fewer committers, then all committers must vote. If even one out of the three does not vote, then the election will end in failure. If the non-voting committer is also not active, then they can, perhaps, be retired by the project lead. Connect with emo@eclipse.org for assistance.

Committer Paperwork

The Eclipse Foundation needs to ensure that all committers with write access to the code, web site, and issue tracking system understand their role in safeguarding the intellectual property of LocationTech. The Eclipse Foundation also needs to ensure that we have accurate records of the people who are acting as change agents on the projects. To ensure that committers understand their role, and that that Eclipse Foundation has accurate records, committers must provide documentation asserting that they have read, understood, and will follow the committer guidelines, and to have their employer sign that they agree that the new committer can participate at LocationTech and can contribute under the terms of the project license.

All committers must complete the Committer Questionnaire and provide documentation as described below.

Committer Questionnaire

The Committer Questionnaire is an online form that must be completed by all new committers. This form offers two separate paths: one for committers who work for a member company that has provided a signed Member Committer Agreement, and one for everybody else.

Note The Committer Questionnaire is accessible only after you have been elected as a committer on a project, either as an initial committer on a new project, or via election on an existing project.

Only member companies that have provided a signed Member Committer Agreement will be listed as member companies in the Committer Questionnaire.

Documents

The exact nature of the documentation required is dependent on your employments status.

What paperwork do you need?
Figure 7. What paperwork do you need?

Documents must be printed, signed and then returned either by fax (using the fax number on the form) or as scanned images via email to emo-records@eclipse.org.

Member Committer Agreement

The Member Committer Agreement (MCA) is used by member companies to cover all of their employees who participate in Eclipse Foundation projects as committers.

If your employer has provided a signed MCA, then you most likely do not require any additional paperwork.

Note MCAs make committer paperwork easy, especially if you work for a member company that employs multiple committers. With an MCA a company can provide signed documentation once, rather than once for each employee (as required for an Individual Committer Agreement).

If your employer has not already provided an MCA, consult with your management team to determine who has the necessary authority to sign it on your company’s behalf. Provide the MCA in advance of the completion of your committer election or new project creation to streamline the committer provisioning process. If you and your management team are not sure whether or not your employer has an MCA, ask EMO Records.

If your employer is a member company that cannot provide a signed MCA, then you’ll have to complete an Individual Committer Agreement and Eclipse Committer Employer Consent Form.

Individual Committer Agreement

The Individual Committer Agreement (ICA) is used by committers who are not covered by an Member Committer Agreement.

You will need to provide an ICA if:

  • You work for member company that has not signed a Member Committer Agreement;

  • You work for a company that is not a member of the Eclipse Foundation;

  • You are self employed or not employed; or

  • You are a student.

If you provide an Individual Committer Agreement, and are employed or self-employed, then you also need an Eclipse Committer Employer Consent Form.

Eclipse Committer Employer Consent Form

Committers covered by an Individual Committer Agreement must document the consent of their employer when participating in Eclipse Foundation projects by providing an Eclipse Committer Employer Consent Form (ECECF).

You will need to provide an ECECF if:

  • You work for member company that has not signed a Member Committer Agreement;

  • You work for a company that is not a member of the Eclipse Foundation; or

  • You are self-employed.

If you are self employed, an owner of your own company, or have full ownership or part ownership in another company and has the authority to sign and submit the Eclipse Committer Employer Consent Form on your own behalf, then they should do so.

Alternatively, you may arrange for the company that is your principal business customer to sign and submit the Eclipse Committer Employer Consent Form on your behalf.

Existing Committer

If you are already a committer on an existing Eclipse Foundation project then additional paperwork may or may not be needed. The EMO IP Team will ask for additional documentation if required.

If that MCA or ECECF already explicitly covers you for the new project, or that MCA or ECECF is universal (for all projects), then no additional paperwork is required

If you are covered by an MCA or ECECF that does not include the new project, then the candidate must provide the documents as described above.

Not Employed or Student

If you are not employed or are a student, send a note to emo-records@eclipse.org explaining your not employed or student status.

Note We require this email because most new committers are employed by a company, the Eclipse Legal Team assumes that is the case for everyone, thus exceptions need to be noted.

Frequently Asked Questions

  1. What happens if I do not fill out the paperwork?

    Then you don’t get your login and password for write-access to the source code repository(s). Sorry. No exceptions.

  2. What happens if I cannot convince my employer to fill out the paperwork?

    The Eclipse Board of Directors has taken a firm position that if you are employed then you must meet one of the scenarios described above. If you cannot convince your employer to fill out the necessary paperwork, then you may not have write-access to project resources. This is the Board’s position even if you are working on LocationTech projects on your own time. We realize that this prevents some talented and desirable people from being able to commit to the projects but this is our IP risk reduction strategy.

  3. Where can I get help to discuss these documents with my management team?

    The EMO and the Executive Director are happy to talk to your management and senior executives about these (and other) legal documents to help them understand why these documents are the best risk reduction solution for everyone involved (The Eclipse Foundation, you, and your employer); just contact us at license@eclipse.org.

  4. What formats can be used to submit paper documentation?

    The Eclipse Foundation accepts any of the following formats for submitting a paper form:

    • Print, sign, and postal mail the form to the Eclipse Foundation;

    • Print, sign, and fax the form to the Eclipse Foundation; or

    • Print, sign, scan, and email to the scan as an attachment to the Foundation

  5. What Email address should I use to send scanned documents?

    Email scans of the completed paperwork to EMO Records at emo-records@eclipse.org.

  6. What if a committer changes employers?

    If you change employers, please contact emo-records@eclipse.org.

Intellectual Property

LocationTech projects are expected to take necessary precautions to mitigate intellectual property (IP) risk to adopters. A company that integrates the code from your project, for example, does so with confidence that the code in the project can legally be distributed under the agreed-to terms. The IP Due Diligence Process, managed by the Eclipse IP Team (commonly referred to as the IP Team), is in place to support this.

All LocationTech committers must be familiar with the Eclipse IP Policy.

Initial Contribution

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 a project’s source code repository.

The IP Team will review your initial contribution to ensure that the code can distributed through a LocationTech property. The IP Team will review the 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 the contribution, this can be a time-consuming process.

Note A project cannot make a release until the due diligence on the IP contained in that release—​including project code contributions and third-party libraries—​is complete.

Create a contribution questionnaire to submit the initial contribution for review by the IP Team.

The IP Team is not able to review the history of project code being moved to a LocationTech project. The IP Team will review a snapshot of the project code and that snapshot, the initial contribution, must be the first commit in the LocationTech repository. If your project uses an existing GitHub repository, the Webmaster team will help you obscure the the history into a hidden branch.

Project Code Contributions

Some contributions of code to maintained by the project (i.e. committed to a project source code repository and maintained by the project team) must be reviewed by the IP Team. The IP Due Diligence Process provides help to determine whether or not the contribution needs to be reviewed by the IP Team. If you’re not sure, ask your project mentors or your PMC for assistance.

All contributions of project code must be tracked in the project’s IP Log.

Create a contribution questionnaire to submit a project code contribution for review by the IP Team.

Third-Party Libraries

All third-party libraries required by project code will have to be checked and approved by the IP Team.

The IP Team must review a third-party library if:

  • the Java/OSGi manifest for one of the project bundles makes a direct reference to a third-party library (either the library bundle or a package from the library);

  • project code includes an import statement for a package from a third-party library;

  • project code uses reflection or other means to reference a library’s APIs and implementation;

  • project code uses OSGi Services to make a reference to a specific implementation of a service; or

  • project code invokes a "command line" tool.

This list is not intended to be exhaustive.

The Guidelines for the Review of Third Party Dependencies can help you determine how to classify your third-party libraries.

Note A project cannot make a release until the due diligence on the IP contained in that release—​including project code contributions and third-party libraries—​is complete.

Create a contribution questionnaire to submit a third-party library for review by the IP Team.

Ownership

The author of a contribution (or their employer) retains ownership of the intellectual property contained in the contribution. As part of the contribution process, the contributor licenses their contribution under the project license.

All source files must include a file header that describes the copyright and license terms of the software.

Example Copyright and License Header
/*******************************************************************************
 * Copyright (c) 2015 Schmedly Inc. and others. 1
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html 2
 *
 * Contributors:
 *   Wayne Beaton - initial API and implementation 3
 *******************************************************************************/
1 Name the initial copyright owner; this must be a legal entity (e.g. a company or individual). If other organizations have contributed, include "and others".
2 List project licenses.
3 Optionally list the names of the contributors and the nature of their contribution.

Your project is not a legal entity and so it is inappropriate to list it as the copyright owner.

Warning The copyright owner is either an individual or their employer. Most employment contracts stipulate that the intellectual property creations of an employee are the property of the employer and so the employer should generally be listed as the copyright owner.

For more information please see the Default Eclipse Foundation Copyright and License Notice.

Licensing

LocationTech top level projects define the standard licensing for their projectsd. If your project has non standard 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.

IPZilla

IPZilla is a modified instance of Bugzilla that tracks the progress of the intellectual property due diligence review and approval process. It is the main interaction point between committers and the Eclipse Foundation’s Intellectual Property (IP) Team. You can review both completed and ongoing reviews via IPZilla.

Note IPZilla is accessible only by committers, Eclipse Foundation member company representatives, and other specifically-designated individuals.

Contribution Questionnaires

A Contribution Questionnaires (CQ) is the main interface between LocationTech committers and the IP Team.

A CQ is started when a committer completes a questionnaire regarding a contribution or third-party library. In literal terms, a CQ is a record in IPZilla, that tracks the progress of the approval process. The CQ record is the primary communication channel between the submitting committer and the IP Team. CQ records persist indefinitely.

All significant contributions of code to be maintained by a LocationTech project, as defined by the Eclipse IP Due Diligence Process require a CQ.

Projects require a CQ for every third-party library that project code makes direct use of (regardless of whether or not the library is directly distributed by the project. If your code makes indirect use of a third party library through another LocationTech project’s code, you do not require a CQ for that library.

Note CQs for third-party libraries are version-specific. That is, a separate CQ is required for different versions of the same library.

CQs are not generally required for ongoing work done by project committers. Consult the IP Due Diligence Process document for more information.

Parallel IP

The Parallel IP Process allows LocationTech projects to make use of project code contributions and third-party libraries before they are fully approved by the IP Team. In practical terms, the Parallel IP Process permits—​with preliminary approval from the IP Team—​a project to check-in code contributions into their source code repository and run builds against third-party libraries without having to wait for the full IP Due Diligence Process to compete.

Note There is some risk associated with the Parallel IP Process. The IP Team will grant preliminary approval based on a cursory review of the contribution; but during their full review, they may uncover issues that require mitigation. This may require, for example, that some parts of a contribution be removed completely (history and all) from a source code repository.

Parallel IP manifests in two different ways: projects in the incubation phase may leverage the Parallel IP process for project code and third-party libraries. Mature phase projects may leverage parallel IP for new versions of third-party libraries for which previous versions have already been approved.

To leverage the Parallel IP Process, projects still submit CQ. The difference is that once a CQ has been reviewed for license compatibility, the project will be authorized via IPzilla to check-in the code start working on it.

All IP must be fully approved before it is included in a release.

Piggyback CQs

Many third party libraries have already been approved for use in LocationTech projects. Many of those are immediately available via the Orbit Project. While these libraries have already been cleared for use by all projects, their use must be tracked. Usage is tracked so that—​in the event that a issue is uncovered following the due diligence process—​we can mitigate the impact of that issue.

In this case, a piggyback CQ can be created on top of an existing CQ. Piggyback CQs are generally approved very quickly as the due diligence work has already been completed.

CQ Workflow

The workflow for creating a CQ for a third-party library starts with a search of existing CQs. If an existing CQ can be found that is concerned with the same library and version, then a piggyback CQ is created. Piggyback CQs must be approved by the project’s Project Management Committee (PMC) before they are processed by the EMO IP Team.

If an existing CQ cannot be found, a new one must be created. Once created, the source code for the third-party library must be attached to the record. The PMC must then approve the record. If the project is eligible to leverage the Parallel IP Process, the IP Team performs a cursory review of the record and—​if the CQ meets with the requirements—​tentatively approves the use of the library while the full review is undertaken in parallel.

The IP team may require your assistance as it performs a deep analysis of the library. Once that analysis is complete and the IP team has made a decision, they will outline the next steps. These next steps may—​in the event that the library is rejected—​that the library be removed from the project VCS, or that some part be removed. Most often, the library is approved and the CQ is marked as such.

Be advised that this process may take a while. The actual amount of time that it takes to process a CQ depends on numerous factors including the size of the queue, and the nature and size of the contribution.

IP Logs

An IP Log is a record of the intellectual property contributions to a project. This includes such as a list of all committers, past and present, that have worked on the code and (especially) those who have made contributions to the current code base.

The IP Log is a big part of the official release cycle. You are required to submit your project’s IP Log prior to scheduling a release, or restructuring review. We encourage you to keep your IP log current rather than rushing at the end. The IP Log includes important information about your project that lets adopters know where all the code comes from, who owns the copyrights, and so forth.

Specifically, the log tracks:

  • Licenses;

  • Past and present committers;

  • Third-party libraries; and

  • Contributions from outside the project (i.e. non-committers)

IP Log Generator

The Automated IP Log Tool automatically generates an IP Log using information that is available to the Eclipse Foundation. The list of committers, for example is generated using information provided by the Dash project which itself pulls information out of source code repositories.

The IP Log generator pulls information from multiple location to assemble the log:

Sources for the IP Log generator
Figure 8. Sources for the IP Log generator
  • Third-party libraries used by the project come from IPZilla;

  • The Dash process scans the project source code repositories to assess committer activity;

  • Dash also scans Git repositories for contributions;

    • If you follow the guidelines for handling Git contributions, contributions received via Git in any branch will automatically appear in the log

  • Contributions received as patches in Bugzilla that are marked iplog+ will automatically appear in the log; and

  • License information is obtained from the Foundation database

To fully leverage the value of the Automated IP Log Tool, you need to:

  • Keep your project metadata up-to-date;

  • Follow the guidelines for handling Git contributions;

  • Mark IP Contributions in Bugzilla; and

  • Create contribution questionnaires (CQs) where appropriate

Warning Contributions should be recorded in one of Git or Bugzilla, not both. Setting the Author credentials on Git commits is the preferred mechanism. The IP Log generator is not smart enough to detect duplicate entries.

Your project’s metadata is used to determine the identities of the source code repositories that Dash needs to scan to find out committer information. Specifically, you need to specify, in the Source Repositories section, a list of paths to source code repository locations.

The Automated IP Log tool populates the Contributors section with information gathered from Git and Bugzilla. This section lists contributions from non-committers (this is time-sensitive, so contributions made by current committers before they became committers will also be included). Only non-committer contributions are recorded in the generated log.

Git commits contributed by non-committers are identified by the author credentials on the commit record; the Author field must be set to the identity of the actual author of the commit.

Alternatively, Bugzilla attachments can be marked with the iplog+ flag. This flag setting indicates that the person who attached the bug is the contributor. To comply with the website terms of use, the person who attaches the contribution must be the person who has permission to make it available. You should ensure that this is the case before including the code in your project’s repository and flagging the entry.

You can also flag an entire Bugzilla entry with iplog+. Doing so, however, indicates to the Automated IP Log tool that every single comment made by a non-committer in the bug report represents a potential contribution. For your own sanity, it’s a good practice to ask contributors to provide and attach patches that can be individually marked. Marking an entire bug represents an ongoing maintenance issue as new comments added to the bug from non-committers will show up in the generated log.

That contributions flagged in Bugzilla will only appear in the IP Log if the bug is marked FIXED or CLOSED.

The Third-Party Software section of the log is populated from IPZilla. The IP Team will mark your contributions in such a way that they will appear in the log. If third party software is not appearing properly, contact the EMO IP Team to make corrections.

Frequently Asked Questions

  1. Do we really need to do this?

    Yes.

  2. What do you do with the IP Log?

    IP Log reviews occur in two stages. In the first stage, the EMO performs a technical assessment to make sure that the artifacts produced by the project are properly accounted for in the IP log. You may be asked to assist with the resolution of any discrepancies found during this assessment. In the second stage, the IP Team reviews the log to ensure that it matches their records. The IP log review concludes with approval by the IP Team.

  3. When should I submit the IP Log for review?

    The IP Log should be submitted for review by the IP Team two weeks before the planned end date for a release review or (if code moves are involved) a restructuring review. Note that the date of your review may be different from the date of the actual release.

  4. Are there other reasons to submit the IP Log for review?

    Generally no. If the IP Team requires an IP Log review outside of the context of a release or restructuring review, they’ll ask for it. It is not generally necessary to submit an IP Log for review outside of the context of a review. It is, however, good practice to do your own review of the generated IP Log periodically to make sure that it accurately reflects the state of the project.

  5. How do I fix problems with the generated IP Log?

    The IP Log is generated based on data from Eclipse Foundation servers. If the log is being generated incorrectly, then the underlying data needs to be fixed. If you spot a problem, send a note to emo@eclipse.org.

Releases

Releases are formal for LocationTech projects. They start with planning, and end with a community review. You can capture as many future releases as you’d like. It’s common practice to specify releases three or six months into the future.

Releases are broadly categorized as:

  • Major releases include API changes (potential for downstream breakage);

  • Minor releases add new functionality, but are API compatible with previous versions; and

  • Service releases include bug fixes only and include no significant new functionality.

For all major and minor releases, you must engage in a release review. Release reviews are not required for bug-fix/service releases.

The Release Cycle
Figure 9. The Release Cycle

A project plan is required for each major and minor project release. The plan should lay out in broad terms what the goals are for the release. As plans are a valuable means for the community to get involved with your project, the plan should be created at the beginning of the release cycle. By establishing the plan early, you give prospective contributors help in determining how they can most usefully contribute, and adopters can prepare their own development schedule and themes. Plans can change during the release cycle.

Use the Project Management Interface to create a new release record. At the start of the release cycle, your plan should minimally include a release number, date, and short description. Think of the description as an "elevator pitch": how would you describe the release in a fifteen second elevator ride? All aspects of a plan can change during the release cycle (including the date). If you do change the plan, make sure that the change is communicated via your project’s dev list and other project channels.

The Plan tab in the release record contains numerous fields for capturing plan information. The amount of information that you should capture for a release plan varies by top-level project, so consult with your Project Management Committee (PMC) for advice.

Producing regular builds is an important part of the release cycle. Builds are an important means of engaging with the community: adopters can help you test your code and test their own so that they can be ready for the eventual release. Plan to produce at least one milestone build (more are better, depending on the length of your release cycle), and capture the planned date for that milestone in the release record. It is also common practice to generate nightly and weekly integration builds. Ensure that your project’s downloads page provides the information required for the community to obtain your builds.

All of your project’s intellectual property contributions must be approved by the IP Team before you can release (this includes third-party libraries and contributions of code to be maintained by the project).

Release Review

A release review is a formal announcement of your release to the community and a request for feedback. In practical terms, experience has shown that those individuals and organizations who are interested in your project follow development throughout the release cycle and so are have likely already provided feedback during the development cycle (i.e. they are unlikely to provide feedback during the review period). With this in mind, the review generally serves as a means for a project to engage in a retrospective of the progress made during the release, discover areas of potential improvement, demonstrate that the project is operating in an open and transparent manner, and ensure that the development process and intellectual due diligence processes have been followed.

Release reviews run for a week and always conclude on a Wednesday.

Note We schedule reviews to conclude on the first and third Wednesdays of the month. Your release date does not have to coincide with the review date (you can set the release date as necessary). The review must, however, conclude successfully before you can make the release official.

A release review requires review documentation and an intellectual property (IP) log check. The review process must be initiated at least two weeks in advance of the anticipated review date.

Release review work flow
Figure 10. Release review work flow

Prepare the review documentation well in advance of the start of the review period. The release record which contains your project plan also includes a Review tab with appropriate fields for a review. As with the plan fields, all of the review fields are optional and the level of detail you need to provide varies by top-level project. You can assemble review information during the release cycle (there’s no need to wait until the end)

The review materials must be approved by the PMC; send an email to the PMC’s mailing list asking for approval. The PMC will respond with feedback or a simple "+1" indicating approval.

Note Click the handy Send Email to the PMC link under Committer Tools on the release record page to connect with the PMC.

Submit the IP Log for review by the IP Team. The IP Team must approve the IP Log before we can schedule the review, so submitting this early is important. The IP Log generator automatically collects information based on the information that the project team has provided to the IP Team through contribution questionnaires in IPZilla, commits in the project’s source code repository, and other information in our databases. Carefully review the IP Log before submitting to the IP Team for their review.

Note Click the handy Generate IP Log link under Committer Tools on the release record page to open the IP Log generator.

The information used to generate an IP Log should always be up-to-date (don’t wait until the end of the release cycle to make it right).

At any point in this process, you can request that the review be initiated by clicking the Schedule a review for this release link that appears at the top of the release record page. This will invite you to select a review date. You must then follow up with the EMO to approve the review.

Note The EMO will likely notice that you’ve created the release record, connected with your PMC, and submitted an IP Log for review by the IP team and will take steps to initiate the actual review. However, since there is a great deal of variability in this process, send an email to emo@eclipse.org stating your intent to release.

The EMO will conclude the review on the scheduled end date and advise the project team of the outcome.

Graduation Review

The purpose of a graduation review is to confirm that the project has a working and demonstrable code base of sufficiently high quality active and sufficiently diverse communities; has adopters, developers, and users operating fully in the open following the Eclipse Development Process; and is a credit to LocationTech and is functioning well within the larger LocationTech community

Graduation reviews are generally combined with a release review (typically, but not necessarily the 1.0 release). Upon successful completion of a graduation review, a project will leave the incubation phase and be designated as a mature project.

For a graduation review, release review documentation must be augmented to include demonstration of:

  • solid working code with stable APIs;

  • an established and growing community around the project;

  • diverse multi-organization committer/contributor/developer activity; and

  • operation in the open using open source rules of engagement.

The graduation review documentation should demonstrate that members have learned the ropes and logistics of being a LocationTech project. That is, the project "gets the LocationTech way".

Frequently Asked Questions

  1. Can a release review fail?

    Technically, yes. A release review can fail. In our history, however, this occurrs very rarely. We set up release reviews to succeed.

  2. Do we really need to do this?

    Yes.

  3. How often should we do releases?

    This depends very much on the nature of your project and the expectations of your community and stake holders. If you’re not sure, connect with your mentors and top-level project for guidance.

  4. How much effort should we put into this?

    The amount of effort varies based on the nature of the team, and expectations of the community and stake holders. Generally, though, a project team shouldn’t spend more than a couple of hours working directly on the formal aspects of the release review. If the amount of effort seems too onerous, you may be trying too hard. Connect with your project mentors, top-level project’s PMC, or the EMO for guidance.

  5. How do I submit the IP Log for review?

    Click the Submit button on the IP Log generator. You need to be logged in as project committer to have access to this button.

  6. Can I accept contributions after I submit the IP Log for review?

    The short answer is yes. Please do accept contributions. If you require a new contribution questionnaire (for either a third party library or code contribution) after submitting the IP Log for review, please ask the IP Team if they want you to resubmit the IP Log.

  7. How do I obtain PMC approval?

    Send the the PMC a note via the top-level project’s PMC mailing list with a link to the release record. Note that the release record page has a handy link labeled Send Email the PMC under Committer Tools.

  8. I need to do a release now. Can you fast-track the review?

    While we do try to be as accommodating as possible, the answer is no. We have a well-defined process with predictable dates. Please plan accordingly.

  9. Can a project in the incubation phase do releases?

    Yes. In fact, we encourage projects to do at least one release while in incubation phase.

  10. What restrictions are placed on version names for incubating projects?

    Projects in the incubation phase generally use version numbers that are less than 1.0. This is, however, a convention not a rule. If it makes sense for you community and adopters to use higher numbers, then do so. If you’re not sure, ask your top-level project PMC for advice.

  11. How do I name/number milestone builds?

    Milestone builds should contain the name/number of the release suffixed with "Mn" (e.g. the second milestone for EGit 3.2 may have a file named "egit-3.2M2"). Projects in the incubation phase may produce milestone builds for their graduation release, e.g "myProject-1.0M2".

  12. How can I get help?

    Contact your mentors (for projects in the incubation phase), top-level project PMC, or the EMO.

Project Management Infrastructure (PMI)

The LocationTech Project Management Infrastructure (PMI) consolidates project management activities into a single consistent location and experience.

Project Management Infrastructure themes:

Improved consistency. Configuration/data-driven project web presence, direct linkage between releases, reviews, and plans. Information—​including basic project metadata, project plans, and release review information—​is captured and retained in a consistent (and easily leveraged) data-based format (rather than in multiple documents in arbitrary formats).

All-in-one-place. Project leads and committers are able to edit information in place on the project information pages. Text/information in one place with links in another is eliminated where possible. Comments and discussion related to reviews, elections, etc. are connected directly to the item being discussed.

Get started faster. By default, projects are provided with a data-driven website that includes consistent links to project releases, reviews, downloads, etc. Projects can opt to override the default and provide their own customized web presence. Setting up a project presence is a matter of configuration, not PHP programming against proprietary APIs.

Project Metadata?

Project committers and project leads are responsible for maintaining their project’s metadata. This information is an important part of being an Eclipse project.

Project metadata is:

  1. Relatively static structural information such as the project description and scope, the names of the project’s mailing lists and newsgroups, the bugzilla products, source code repositories, etc.

  2. Historical information such as previous release downloads, release review slides and IP logs, etc.

  3. Status and future looking information such as the project and milestone plans, the features scheduled for the current release, release dates, etc.

PMC members, and the Eclipse Foundation staff also have the ability to make changes on behalf of a project.

Viewing

The complete listing of all current LocationTech projects provides one starting point for viewing projects. From here, you can link directly to a project information page. Navigation options are provided to help you move from one project to another.

Commands and Tools

Committers have access to several committer-specific commands and tools. The selection of commands available are context sensitive; only those commands that make sense for the logged in user are shown.

Editing Project Metadata

Committers have the ability to edit the information managed and displayed on the project page. There are several sections on the page. When you switch the page into "Edit" mode, you will be provided with lots of help regarding the contents of each of the fields (note that the help text is currently rendered below the fields).

Some of the fields are described below.

Description and Scope

The description should start with a concise paragraph of three to five sentences (e.g. suitable for display with a collection of other projects). A single paragraph is generally appropriate for the description.

If more than a single simple paragraph is required to fully describe the project, it is possible to set a summary. The summary can be specified by toggling the "show summary" link to explicitly set a summary apart from the more detailed description, or the top part of the description can be designated as the summary by inserting a Teaser Break into the content.

Note providing a summary gives you control over what will get rendered. In views where we are displaying more than one project, the system will artifically cut short descriptions that are too long, potentially resulting in a description that looks weird.

The scope is intended for a more select audience; generally speaking the scope should be taken directly from the project’s proposal. Project members have the ability to change the text of the project scope, but should be careful to avoid changing the meaning. If the meaning of the scope needs to change, the Project Management Committee (PMC) must be contacted regarding a potential restructuring review.

Downloads

You can provide download information for your project in the "Downloads" section.

The first entry is the main "Downloads URL". This manifests as a "Big Button" Download on the project page. What you put here is left to the project team to decide. It can be a link to a webpage, a direct link to a file download, or whatever else makes sense the project and community.

Optional text can be included along with the "Big Button" Download, as well as links to zero or more Eclipse Marketplace, update/p2 sites, or other downloads. Each of the links can have an optional title (the link itself will be displayed if no title is provided). Note that no validation is done on the links to ensure that they are meaningful.

Source Repositories

The project can specify zero or more source repositories. These are displayed in the "Contribute to this Project" section.

The values specified are used to query against a database of known existing source repositories (this database is updated nightly by a discovery process). Those repositories that are found in the database will be displayed with enhanced information (including links to repository mirrors, Gerrit, etc.). All values that you provide will be displayed, whether they point to real repositories or not. If the database does not contain your repository, the PMI will assume that the value is correct and try its best to display the information.

Repositories should be specified using the file system path, e.g. /gitroot/egit/egit.git. The name that is displayed for the repository is extracted from the last segment of the URL.

If a description file exists in the Git repository, the contents are automatically displayed under the repository name.

Note The script that we us to identify repositories attempts to identify a corresponding Gerrit interface for the repository. If it exists, the Gerrit URL is used in place of the Git one. If the repository uses Gerrit, then only the Gerrit URL is displayed. Otherwise, the "git://" and "ssh://" URLs are displayed.

You can use wildcards to match multiple repositories, e.g. /gitroot/virgo/*. Note that wildcards only work for repositories that exist on LocationTech infrastructure (they do not work for GitHub-based repositories, for example).

Repositories are displayed in the order they are specified. The order can be changed in the edit screen by dragging entries into the desired order. All wildcard matches are sorted alphabetically by name at the end of the list.

A Contribution Message should be provided; it is displayed at the top of the section and is one of the primary means by which the community will find the project code. Arbitrary text is permitted, but we recommend that you limit this content to a single paragraph with a few sentences that include a link to more information.

Company Logos

Company logos automatically appear on the Who’s Involved page under the following conditions:

  • The company must be a member of the Eclipse Foundation;

  • The company needs to have their logo uploaded to the Portal;

  • At least one committer has to be listed as an employee of the company in question;

  • The committer must be on this project; and

  • The committer must be active (must have made at least one commit in the last three months)

If all of those conditions are met and the logo is still not showing up, then it’s possible that the project meta-data doesn’t have the correct source code repository information specified.

Build Technology

A project can specify a section of text, links, and a selection of the build technologies employed. Specifying this information makes it easier for members from the community to understand your build. Links can include direct links into the Hudson builds, pages of build instructions, or whatever else the project team feels will help the community build the project.

Technology Types

A project can specify the types of technology produced by the project. This is specified in rather broad terms like "OSGi" or "Runtime". The various technology types manifest as checkboxes on the edit screen. This information is used to form connections between projects to assist in navigation and discovery.

Clicking on one of the technology types, will take the user to a page that lists the projects that produce that particular type of technology, along with the summary of their description and project logo (if specified).

Releases and Reviews

Projects, Releases, and Reviews are presented as separate records. Each project record, obviously, represents information about a project. A project may have multiple releases; information about the release is represented in a release record. The release record also contains some review information. This information is included here, because all releases do not necessarily have a review (a project can opt to provide some review type information as part of a release record. A project can have multiple review records; as release reviews are the most common form of review, most review records will be joined to a release record.

The relationship between proposals, projects, releases, and reviews.
Figure 11. The relationship between proposals, projects, releases, and reviews.

A review record, however, does not require a release association. Some reviews are associated with proposals. Other have no other association (e.g. termination reviews).

Each release has its own record in the database. Records are connected directly to a single specific project; a subset of release records associated with a project are displayed on the project page. An existing release can be edited in much the same was as a project. Any logged in project member (committer or project lead) can click the "Edit" button.

Note Create a single record for each release. Do not create release records for milestones. Enter milestone information in the Plan information for your release.

A project lead or committer can create a new release by clicking "Create a new release" under "Committer Commands" on the project page. This opens a dialog requesting that a date and name be specified. Both of these values can be changed later.

Description

Describe the release in the Description section. The description should generally be a concise paragraph describing the focus of the release (e.g. adding certain functionality, fixing bugs, etc.) in a form that is appropriate in an aggregation (e.g. a page that displays the release information for all projects participating in an instance of the Simultaneous release). The description should provide enough information to encourage the reader to click the "find out more" link.

Issues

The release record will automatically generate a list of targeted bugs.

To populate this list:

  • Ensure that the Bugzilla Product is set the to correct value in the project metadata;

  • Set the "target milestones" in Bugzilla need to match the name of your release.

Note The matching algorithm tries to be as forgiving as possible, a release named "3.5", "3.5.0", or "3.5 (Luna)" will—​for example—​match target milestones named "3.5" ,"3.5M1", "3.5 M2", "3.5.0M3", etc., but will not match "3.5.1".

The bugs for all projects participating in the release will be included. Bugs are grouped by Bugzilla product and component.

Plan

Project plan information belongs in the Plan section. This information should generally be provided early in the development cycle to allow the various communities the ability to understand and participate in the release. It is expected that the plan will evolve over time. Note that all projects are required to provide a plan for each major and minor release (plans are not required service releases).

Milestones

Enter the name, date, and optional description for each milestone expected with the release.

Projects should generally include more than one milestone build with each release. To include additional milestones, click the "Add another item" button. Note that milestones can be dragged into the desired order. To remove a milestone, leave the "Name" field blank.

Review

The release has a Review section that can be used to provide information for the associated review. If you provide information here, the release record itself can be used as review documentation; no further documentation is required.

Each section on the review page includes a little help to describe the sort of information that you should provide.

All major and minor releases require a review. Service releases (i.e. bug fix releases that do not change public APIs or add new functionality) do not require a review.

If a release requires a review, you can schedule one by clicking the "Schedule a review" button. The drop-down list above the button contains several options for review dates. Pick the one that works best for you.

Note that this form will not appear if a review has already been scheduled, or the release date does not provide enough time to run a review (or is in the past). If a review has been scheduled, a link to the review will appear.

You can edit the review document, but there’s really not all that much to edit. A free-form text field is available and can be used if there is some need to provide review-specific information that might not otherwise be an appropriate part of the release record. This field is intended for other types of review (e.g. restructuring or termination reviews); we decided to leave it available for release reviews for cases in which it might be useful rather than suppress it.

When the review is displayed, it automatically includes the review information from the release record; it shows the review-specific information at the top of the page, and includes the review information from the release as the rest of the page contents.

This can make things a bit confusing when you want to make changes to the metadata for a review record. Just remember that the review information for a release is stored in the release record.

Glossary

Architecture Council

The Eclipse Architecture Council (AC) serves the community by identifying and tackling any issues that hinder Eclipse’s continued technological success and innovation, widespread adoption, and future growth. This involves technical architecture as well as open source processes and social aspects. Comprising the finest technical leaders from all community stake holders, it is the council’s goal to keep the projects successful and healthy, the processes simple and smooth, and the communities vibrant and cohesive.

Architecture Council Mentor

The Eclipse Architecture Council (AC) is a body of battle-hardened Eclipse committers. All new projects are required to have at least one mentor 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.

Board of Directors

The business and technical affairs of the Eclipse Foundation are managed by or under the direction of the Board of Directors (or more simply, "The Board").

Committer

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 LocationTech source code repository is clean from an intellectual property point of view. This is discussed with more detail below.

Community

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, the community is enormous. Other projects have smaller communities. Developing a community is a very important part of being a LocationTech 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 LocationTech Community is formed from the union of the communities that grow around individual projects.

Contribution Questionnaire

Prior to committing a significant contribution of content from a non-committer to a LocationTech project, the committer must fill out a contribution questionnaire (CQ) and submit it to the IP Team 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.

Contributor

A contributor is anybody who makes contributions to the project. Contributions generally take the form of code patches, but may take other forms like comments on issues, additions to the documentation, answers to questions in forums, and more.

Dash Process

The Dash Process, or simply Dash, is a collection of scripts and processes that harvest project data for dissemination in charts, IP Logs, and more.

Dev-list

Every project has a development list or dev-list. All project committers must subscribe to the list. The dev-list should be the primary means of communication between project committers and is the means throuh which the Eclipse Foundation’s automated systems communicate with the project.

Ecosystem

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 LocationTech technology. This takes the form of including LocationTech code in products, providing support, and other services. You become part of an ecosystem 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.

Eclipse

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 ecosystem, and—​of course—​The Eclipse Project (which is just one of the top-level projects hosted by the Eclipse Foundation). Confusing? Yes.

EMO

The Eclipse Management Organization (EMO) consists of the Eclipse Foundation staff, and the Architecture and Planning Councils. 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 best method of contact with the EMO is by email (emo@eclipse.org). If you have a question that cannot be answered by project lead, mentor, or PMC, ask the EMO.

EMO Executive Director

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

EMO IP Team

The EMO Intellectual Property Team (commonly referred to as the IP Team) is responsible for implementing the intellectual property policy of the Eclipse Foundation.

EMO Records

The EMO Records Team (commonly referred to as EMO Records) is responsible for managing committer paperwork and other records on behalf of the Eclipse Foundation. Contact the EMO Records team via email (emo-records@eclipse.org).

Incubation Phase

The purpose of the incubation phase is to establish a fully-functioning open-source project. In this context, incubation is about developing the process, the community, and the technology. Incubation is a phase rather than a place: new projects may be incubated under any existing project.

IP Due Diligence Process

The Intellectual Property Due Diligence Process defines the process by which intellectual property is added to a project. All LocationTech committers must be familiar with this process.

IP Log

An IP Log is a record of the intellectual property (IP) contributions to a project. This includes such as a list of all committers, past and present, that have worked on the code and (especially) those who have made contributions to the current code base.

Member Company

The Eclipse Foundation and Eclipse community is supported by our member organizations. Through this support, the Eclipse Foundation provides the open source community with IT, intellectual property, and marketing services.

Parallel IP

The Parallel IP Process allows a LocationTech projects to make use of project code contributions and third-party libraries before they are fully approved by the IP Team.

Planning Council

The Planning Council is responsible for cross-project planning, architectural issues, user interface conflicts, and all other coordination and integration issues. The Planning Council discharges its responsibility via collaborative evaluation, prioritization, and compromise.

Project

Projects are where the real work happens. Each project has code, committers, and resources including a web site, 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 web site. Projects are sometimes referred to as subprojects or as components. The Eclipse Development Process, however, treats the terms project, subproject, and component as equivalent.

Project Lead

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

PMC

Each top-level project is governed by a Project Management Committee (PMC). The PMC has one or more leads along with several members. The PMC has numerous responsibilities, including the ultimate approval of committer elections, 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.

PMI

The Project Management Interface (PMI) is the system that tracks the state and progress of LocationTech projects. Project committers can modify the the information represented in the PMI, including the project description, and information about project releases. Automated systems use this information to, for example, generate dashboard and chart information for the project, intellectual property logs, etc.

Top-Level Project

A top-level project (sometimes referred to as a TLP) is effectively a container for projects that do the real work. A top-level project does not generally contain code; rather, a top-level project contains other projects. Each top-level project defines a charter that, among other things defines a scope for the types of projects that it contains. Top-level projects are managed by a Project Management Committee.

Webmaster

The Webmaster team is responsible for maintaining the IT infrastructure of the Eclipse Foundation and the LocationTech forge. You can contact the Webmaster team directly via email (webmaster@eclipse.org).

Working Group

Eclipse Working Groups provide a vendor-neutral governance structure that allow organizations to freely collaborate on new technology development.

Getting Help

If you have any questions, or are unsure of your responsibilities as a project lead or committer, please contact your project mentors or EMO.