Skip to main content

Eclipse Foundation Specification Process Operations Guide

The Eclipse Foundation Specification Process (EFSP) provides definitions and a framework for the governance of open source development of specifications at the Eclipse Foundation.

The Eclipse Foundation Development Process (EDP) is the foundation upon which the EFSP is based. It provides definitions and a framework for the governance of open source development at the Eclipse Foundation.

The Eclipse Foundation Intellectual Property (IP) Policy describes the policies and mechanisms that the Eclipse Foundation uses for accepting and licensing the intellectual property developed by Eclipse projects and specifications.

The Eclipse Foundation Working Group Process (EFWGP) defines the process for creating and managing Eclipse Foundation Working Groups, and how Eclipse Foundation members lead, influence, and collaborate within Working Groups. The corresponding Eclipse Foundation Working Group Operations Guide describes the lifecycle and operation of Eclipse Foundation Working Groups.

In the event of a conflict between this document and the documents listed above, the documents listed above take precedence.

Projects and Specifications

The EFSP focuses on specification projects in matters of governance (e.g. project structure, committers and project leads). That is, in matters of governance, open source projects are the atomic unit.

Specification projects are a special type of open source project. In mathematical terms, a specification project (as defined by the EFSP) can be thought of as a subtype of project (as defined by the EDP). The EDP describes governance that applies to both projects and specification projects; the EFSP defines additional governance that applies to specification projects.

Specification Project (EFSP) is a subtype of project (EDP) that contains specifications.
Specification Project (EFSP) is a subtype of project (EDP) that contains specifications.

A specification project may be the host of more than one specification.

A specification project may have more than one Git repository.

Git repositories are assigned to projects not specifications. Project resources, like Git repositories, are managed by the Eclipse Foundation at the project level.

Committer status is granted on projects not specifications. That is an individual is said to be a committer on the corresponding project, and as such has committer-level access to all resources assigned to the project. In the case of specification projects that manage the lifecycle of multiple specifications, all committers have the same level of access to all resources (e.g., Git repositories) allocated for all specifications.

There is no formal notion of specification lead. Specification projects must have one or more project leads, as that role is defined in the EDP. Specification projects may choose to have a de facto notion of a specification lead, but that role has no formal standing in the specification process.

Development of a new version of an existing specification occurs in the context of the existing specification project. That is, the specification project, along with its team of committers and associated resources, persists beyond the release of any particular version of a specification. After a specification is released, the same specification project with its associated committers and resources are used to plan, develop, and release subsequent versions of the specification.

A specification project produces all versions of a specification
A specification project produces all versions of a specification

Specification projects engage in releases and reviews. This one is more subtle and only applies to specification projects that support the development of more than one specification. The EDP allows projects to engage in releases that contain some subset of their content, so the notion of engaging in, for example, a release (and corresponding release review) for one single specification is fully supported. While, strictly speaking, this sort of hypothetical release would be a project release and be owned by the project, it would be a specification release in a practical sense. There are no requirements regarding how releases are named/numbered.

Specification projects operating under the EFSP follow the same lifecycle as open source projects operating under the EDP with the additional requirements that they engage in a plan review at the beginning of a development cycle, that they engage in a release review for all major and minor releases, and that all reviews be approved by super-majority ballot of the working group’s specification committee.

Working Groups and Specifications

Specifications are created and maintained by specification projects. Each specification project is aligned with exactly one Eclipse Foundation working group. Specification projects are said to work under the purview of a particular working group, or—​more specifically—​the specification committee of a working group.

Working groups provide governance for specification projects. A working group’s specification committee, must approve—​by super-majority ballot—​all reviews.

The specification committee ratifies specifications as final. Via ballot during a release review the working group’s specification committee must vote to a approve ratifying the release version of a specification as a final specification. Approval by a super-majority of the specification committee is required.

Specification project committers write the specification. Committer and specification committee member are two distinct roles. Being granted one of these roles does not automatically grant the other. Specifically, holding the role of specification committee member does not grant any write privileges on specification project repositories.

Roles

Specification Committee

The specification committee is responsible for implementing the EFSP for all specification projects (as that term is defined by the EFSP) that operate under the purview of the a working group. A working group may, via their charter, assign specification committee responsibilities to another committee.

The specification committee is ultimately responsible for ensuring that the final specifications produced by the working group’s specification projects make sense. The definition of “makes sense” varies by specification committee participant, but is generally understood to mean that the specification can be implemented and that those aspects of the Eclipse Intellectual Property Policy with regard to essential claims are observed. In practical terms, specification committee participants wield power via the ballots that are required to approve key lifecycle events per the EFSP.

The Specification Committee is responsible for producing, publishing, and maintaining operational guidance documentation for specification projects. This includes the minimum requirements and process for producing a final specification. It also includes operational guidance for running a specifications TCK for the purpose of testing for compatibility.

The Specification Chair (or their delegate) is responsible for initiating ballots, tallying their results, disseminating them to the community, and (when appropriate; e.g., in the case a release review ballot) reporting them to the EMO.

The Specification Committee is also responsible for defining and refining how they implement the EFSP for those Specification Projects under their purview.

Project Management Committee

The primary role of the Project Management Committee (PMC) is to ensure that project teams are implementing the EDP. In particular, the PMC monitors project activity to ensure that project teams are operating in an open and transparent manner. The PMC reviews and approves (or vetos) committer elections, first validating that candidate committers have demonstrated sufficient merit.

The PMC is further responsible for ensuring that project teams abide by the Eclipse IP Policy and implement the IP Due Diligence process. In practical terms, the PMC approves intellectual property contributions (CQs) and provides (limited) guidance to project teams regarding intellectual property (deferring to the Eclipse IP Team as necessary).

The PMC is responsible for the structure of the top-level project and the organization of the open source (software and Specification) projects contained within.

The PMC is a link in the project leadership chain. As such, the PMC has a role in the grievance handling process: they identify and document project dysfunction (with the responsibility to remove/replace/add disruptive committers).

The PMC provides other oversight regarding the operation of open source projects. They review and approve release and progress review materials, and facilitate cross-project communication within the top-level project.

Project Lead(s)

A specification project has one or more project leads. Project leads are the main liaison between the project team and the Eclipse Management Organization (EMO), and are responsible for ensuring that team members are implementing their responsibilities under the EDP, EFSP, and the Eclipse Foundation’s IP Policy. The lead is responsible for initiating reviews as the project reaches the appropriate milestone.

Participant Representative

The EFSP states that a member participant may appoint a participant representative committer. A member participant is defined as a strategic member or contributing member of the Eclipse Foundation that is a participant in the working group (i.e., has signed the corresponding working group participation agreement). In the case of specifications, vendor-neutrality trumps meritocracy. A specification process must be accessible to all companies who wish to participate.

Appointment of a participant representative:

  • Is the mechanism by which their patent portfolio is licensed to the resulting specifications;

  • Ensures that the specification process is accessible to all companies that wish to participate; and

  • Is consistent with how all other specification processes work.

The notion of a participant representative specifically excludes committer members; this makes sense as, to be a committer member participant (the EFSP refers to this an an individual participant) in a working group, one must already be a committer. This does mean, however, that an individual participant who is a committer on one specification project cannot appoint themselves as a participant representative on another.

Appointing a participant representative this is a power that a member participant will use to ensure that they have at least one committer on a specification project. If the member participant already has an employee as a committer, then that member participant is considered to already have a participant representative and cannot appoint another.

Additional committers can be added via committer election.

Reviews

Specification projects in active development must engage in a progress or release review at least once per year. In practical terms, this means that the clock starts ticking when the plan review that occurs at the beginning of the development cycle concludes successfully, and is reset following a successful progress review.

The entire process is halted when either the specification project engages in a successful release review (thereby concluding the development cycle), or the specification team decides to abandon the cycle.

The PMC approval and the specification committee ballot are different activities with different intention and purpose.

The primary role of the PMC is to ensure that project teams are implementing the EDP. In particular, the PMC monitors project activity to ensure that project teams are operating in an open and transparent manner. Any specification project committer or project lead can solicit approval for a release from their PMC by posting on the PMC’s mailing list.

The Committer Tools block on the right side of the project page contains links subscribe to the PMC’s mailing list ("PMC Mailing List") and to send a note ("Send Email to the PMC").

The specification committee is ultimately responsible for ensuring that the ratified final specifications produced by the working group’s specification projects match the working group’s purpose and goals, that they can be implemented, and that those aspects of the Eclipse Intellectual Property Policy with regard to essential claims are observed. The specification committee exercises their responsibility via ballot.

Creation Reviews

A creation review is required before a new specification project is created. In the case where an existing open source project is converted into a specification project, or a specification moves from working under the supervision of one working group to another, the creation review will be combined with a restructuring review.

Creation reviews are tracked and managed by the EMO. A creation review requires a ballot of the specification committee. The ballot may be initiated directly by a member of the specification committee; the EMO can provide assistance if required.

In considering their vote in the ballot, the question that specification committee members must consider is whether or not they would vote to approve the eventual release, ratification, and creation of a Final Specification when the project returns for a release review. If the answer is yes, then the specification committee member should vote in the affirmative +1; they should either vote in the negative -1 or abstain +0 otherwise.

Plan Reviews

Plan reviews occur at the start of a development cycle. A creation review serves as the plan review for a specification project’s first release.

Plan reviews are not formally tracked or managed by the EMO, but rather are initiated and managed directly by a member of specification committee; the EMO can provide assistance if required. In practice, a plan review requires no more formal ceremony than a successful ballot of the specification committee.

When reviewing a plan, the question that specification committee members must consider is whether or not they would vote to approve the eventual completion of the plan when the project returns for a release review. If the answer is yes, then the specification committee member should vote in the affirmative +1; they should either vote in the negative -1 or abstain +0 otherwise.

Ideally, when casting their vote, specification committee members should focus less on the mechanics of implementing the plan and more on the broader implications of the themes and changes suggested in the plan to implementors, adopters, and the ecosystem.

Release Reviews

A release review is required for all major and minor releases from a specification project. The review may be skipped for service releases that do not implicate any new intellectual property (i.e., bug fixes only). A specification project must engage in a release review for the first release of all specifications (independent of whether or not it is a major, minor, or service release).

Releases of specification projects operate under the EDP augmented by the EFSP. Release reviews are tracked and managed by the EMO. A release review requires a ballot of the specification committee. The ballot may be initiated directly by a member of the specification committee; the EMO can provide assistance if required.

See release and progress reviews for a more complete description of the release review process.

It is up to the individual parties to determine the basis on which they will vote in the ballot. When determining how to vote in a release review ballot, the question that specification committee members must consider is whether or not they believe that the specification as written can be implemented, that the TCK is complete enough, and whether or not the project team has met their obligations under the EFSP. If the answer is yes, then the specification committee member should vote in the affirmative +1; they should either vote in the negative -1 or abstain +0 otherwise.

Progress Reviews

A progress review is required by a specification project when the time elapsed between a plan review and a release review exceeds one year.

Progress reviews are tracked and managed by the EMO. A progress review requires a ballot of the specification committee. The ballot may be initiated directly by a member of the specification committee; the EMO can provide assistance if required.

When determining how to vote in a release review ballot, the question that specification committee members must consider is whether or not they believe that the specification is progressing in a manner that will produce a specification that can later be ratified. If the answer is yes, then the specification committee member should vote in the affirmative +1; they should either vote in the negative -1 or abstain +0 otherwise.

Ballots

Specification ballots are run in the specification committee’s public mailing list.

A ballot is initiated by a member of the specification committee by sending an email to the specification committee’s public mailing list, inviting specification committee members to indicate their vote in the affirmative with a +1, the negative with -1 or their decision to abstain with +0. Specification committee members express their vote by responding on the public mailing list.

Specification committee members vote on behalf of their constituency (generally the company whose interests they represent on the committee, or—​in the case of an elected representative—​their electoral base). The basis upon which this decision is made is at the discretion of the individual specification committee member. The specification committee may decide to establish a set of guidelines or requirements to provide a basis for voting; though these may instead be regarded as a gate to even starting a ballot.

The following templates can be modified accordingly and used to initiate a ballot.

The ballot initiation message does not need to follow these templates; they are provided here only as a convenience.

Release Review Ballot Template

Title: BALLOT: Approval to Release the <specification> Specification Project

Your vote is required to approve and ratify the release of <specification>.

The Eclipse Foundation Specification Process (EFSP) requires a successful ballot of the specification committee in order to ratify the products of this release as a Final Specification (as that term is defined in the EFSP).

<details>

Per the process, this will be a <duration> day ballot, ending on <date> that requires a super-majority positive vote of the <working-group> specification committee members (note that there is no veto). Community input is welcome, but only votes cast by specification committee representatives will be counted.

Specification committee representatives, your vote is hereby requested. Please respond with +1 (positive), +0 (abstain), or -1 (reject). Any feedback that you can provide to support your vote will be appreciated.

Restructuring Review Ballot Template

Restructuring Reviews are used to change the structure of a project. A restructuring review would be used to, for example, move a specification from one project to another, move a specification project from one working group to another, or convert an existing open source software project into a specification project.

Title: BALLOT: Approval to change the <project> into a Specification Project

We need to restructure the existing <project> into a specification project as defined by the Eclipse Foundation Specification Process (EFSP). For this, the EMO has initiated a restructuring review.

The purpose of a restructuring review is to change the nature of a project. While we are not strictly creating a new project, we are in a manner of thinking, creating a new specification project from an existing project. With this in mind, we are treating this as a creation review from the perspective of the specification committee approval requirement.

Per the process, this will be a <duration> day ballot, ending on <date> that requires a super-majority positive vote of the <working-group> specification committee members (note that there is no veto). Community input is welcome, but only votes cast by specification committee representatives will be counted.

<details>

Specification committee representatives, your vote is hereby requested. Please respond with +1 (positive), +0 (abstain), or -1 (reject). Any feedback that you can provide to support your vote will be appreciated.

Details

The <details> should concisely describe the changes that are proposed. This could be as simple as a statement stating that "The Eclipse Foo project will be converted into a specification project.", but other changes may be included.

For example:

We will rename "Eclipse Project for JTA" project to "Jakarta Transactions" and convert it into a specification project with this project/specification scope statement:

Jakarta Transactions defines a standard that allows the demarcation of transactions and the transactional coordination of XA-aware resource managers as described in the X/Open XA-specification and mapped to the Java SE XAResource interface within Java applications.

Specializing the EFSP

A working group may, through their specification committee, choose to specialize the EFSP for their own implementation. The process document is a foundational document that defines underlying principles, fundamental rules, and other requirements with regard to implementing specifications. The process document does not generally prescribe the use of specific technology, or provide any detail with regard to implementation.

This document starts by describing what must not be taken away from the specification process, and concludes with some suggestions of what might be considered for a working group’s specialization of the process.

Minimum Values

The most critical aspect of the EFSP is the management of essential claims as defined by the Eclipse IP Policy. In this regard, the requirement that all committers be covered by an Eclipse Foundation Membership Agreement and Working Group Participation Agreement cannot be relaxed. By extension, the restrictions placed on participants and participant representatives cannot be relaxed in any customization of the process, nor can the ability of a participant to appoint a participant representative be inhibited in any way.

The requirements regarding scope must not be relaxed. Specifically, the requirements regarding approvals and the requirement that the development work of the project stay with the boundaries defined by the scope must not be curtailed.

The underlying principles of open source (the so-called “Open Source Rules of Engagement”) may not be curtailed. Specifically, all specification projects must operate in an open and transparent manner, must follow meritocratic practices to promote individuals to positions of power and authority, and (although not strictly listed as a rule of engagement) operate in a vendor neutral manner.

The powers granted to the project leadership chain by the EDP must not be restricted.

In general, quantities included in the EFSP and EDP can be increased, but not decreased. For example, the period of time required to run a simple ballot (e.g. a committer election) must not be less than seven days (it is generally accepted at a week is a reasonable minimum period of time to run a ballot that meets a minimum standard of community inclusion).

Specializing the Process

The EFSP defines a set of underlying principles and fundamental requirements. It intentionally does not define any sort of practical implementation, or prescribe any specific technologies. Specializations of the process should take a similar approach. The process might, for example, extend the amount of time required for a specification committee ballot; but any attempt to describe the specific mechanisms and technology by which a ballet is run in a practical sense is more of an operational detail that should be defined in an operations document.

Example Process Specializations

Providing a comprehensive list of every possible thing that can be customized is an impossible task. In place of a comprehensive list, we provide a list of examples of things that might be customized and/or tuned.

A customization may extend the list of Open Source Licenses (but many not remove licenses from the master list).

A customization may define requirements for evolving itself to create future versions of the working group-specific specification process.

A customization may:

  • Require progress reviews at some interval;

  • Specify a maximum and/or minimum period of time required for specification committee approval ballot;

  • Specify the period of time that must pass between reviews; and

  • Describe mitigation steps in the event that a review fails.

The process requires that a specification project engage in a release review. A customization may:

  • Specify a maximum and/or minimum period of time required for specification committee approval votes;

  • Specify the period of time that must pass between the last progress review and the release review; and

  • Describe mitigation steps in the event that the review fails.

A customization may also define:

  • Technical namespaces;

  • Criteria for designating a release as major, minor, or service; and

  • Criteria, requirements, etc. for managing exceptions in a TCK.

While generally considered best practices, a customization may prescribe:

  • How a specification is bundled for dissemination;

  • Specific file formats for documentation; and

  • Document structure and style.

The EFSP provides no specific criteria for designating a specification as a profile, nor does it attempt to define “platform”. A specialization may choose to provide definitions or specify the criteria for designating a specification as a profile.

Operational Considerations

Specification committees are encouraged to create an operations document that describes how the process is implemented. The evolution of an operations document tends to be organic, based on building consensus within the team instead of relying on a formal approvals process.

Out of convenience, an operations document may repeat information that’s captured in the process; as such, an operations document must include a clear statement that in the event of conflict the process document must be taken as the authority.

The practical implementation of aspects of the process are not defined by the EFSP, and so a working group specification process (specialization) may choose to formalize (for example):

  • How to run specification committee ballot;

  • How a participant appoints a participant representative;

  • What to do when a ballot fails or approval is not otherwise granted;

  • The mechanism by which a specification committee determines whether or not a minor correction made during a ballot changes semantic meaning;

  • How a specification version becomes a final specification;

  • Requirements/guidelines to pass a progress/release review, along with timing of the review itself; and

  • A standard means of describing relationships between specifications.

Frequently Asked Questions

Is a specification project is a subtype of a Eclipse project, governed by the EDP?

In a mathematical sense, yes. A specification project as defined by the EFSP is a specialization or subtype of an Eclipse open source project as defined by the EDP.

Does a specification need to list patents?

No. In fact, a specification must not specifically list patents.

How do patent grants work?

We cannot provide legal advice. Connect with your lawyer for more information.

Can a working group’s steering committee take on the responsibilities of the specification committee?

Yes. A working group’s charter can assign the responsibilities of the specification committee to any working group committee.

The ability of a member participant (i.e., a participant representing a company) to appoint a participant representative committer isn’t very meritocratic; is meritocracy irrelevant?

Meritocracy is very relevant. However, the rules of engagement with specification projects is different in consideration of factors like patent grants and antitrust. In the case of specifications, vendor-neutrality trumps meritocracy: a specification process must be accessible to all companies who wish to participate.

Can a member participant (i.e., a participant representing a company) appoint as many participant representative committers as they’d like?

No. A member participant (i.e., a company that is a participant in the working group) can appoint a single participant representative committer on a specification project, and only if they do not already have a committer representing their interests on that project. Additional committers representing the interests of a member participant may demonstrate merit through contribution and be elected to the project using the standard mechanism for electing committers.

Is a participant representative a special kind of committer?

A participant representative is indistinguishable from any other committer once appointed.

Do participant representatives have any special powers or privileges?

No.

Will a participant representative be retired from a specification project when they change employers?

No. A participant representative is indistinguishable from any other committer and so retains their committer status even after changing employers. After changing employers, a committer may require new committer agreements, but once those are in place, the committer retains all privileges. In the event that a committer changing employers leaves a member participant unrepresented, that member participant may appoint a new participant representative.

Back to the top