Eclipse Foundation Specification Process Step-by-Step

Scientific progress goes “boink”? – Hobbes

The Eclipse Foundation Specification Process (EFSP) provides a framework and governance model for developers engaged in the process of developing specifications.

Specification: A specification is a collection of related artifacts.

The EFSP defines a specification as a “collection of Application Programming Interface (API) definitions, descriptions of semantic behavior, data formats, protocols, and/or other referenced specifications, along with its TCK, intended to enable the development and testing of independent Compatible Implementations.” A specification project is, then, an Eclipse open source project concerned with the creation and maintenance of one or more specifications.

As a matter of practice, we tend to have a one-to-one mapping between specification projects and specifications. But there are examples of specification projects that play host to multiple specifications. The Eclipse Project for Stable Jakarta EE APIs, for example, is the host project for a handful of specifications that are considered stable and in long term maintenance (and not expected to continue to evolve).

Specification Project: A specification project is the composition of a team of committers dedicated to the creation and maintenance of one or more specifications, along with the resources required to create those specifications.

Resources assigned to a specification project include one or more software repositories that serve as the collaboration point for the development of specification documents and corresponding technical artifacts. A specification project has other resources assigned to it, including space on a download server, build resources, and mailing lists.

A specification project may also be responsible for other related functionality, including TCKs. It’s considered a best practice to keep implementations of a specification separate from the specification itself, but there is no rule that prevents this sort of coupling.

A specification project has one or more project leads who are typically also committers. Project leads have no special powers or authority with regard to development and delivery of specifications. Rather, they are the primary liaison between the project team and the Eclipse Foundation, and form the first link in the leadership chain which includes the Project Management Committee (PMC) and Eclipse Management Organization (EMO). Primarily, project leads are responsible for ensuring that the project team (i.e. the committers) are following the rules.

Specification Versions: A specification project produces versions of a specification, which the EFSP refers to as specification versions. Once ratified, a specification version becomes a final specification.

The differences between a specification version and a final specification are subtle. A specification version is the output from the open source project. While a final build of a specification version can be said to be complete, it cannot be used as the basis for an implementation. The intellectual property rights that are required to implement a specification flow through the final specification (a bit more on this later).

No specific packaging or means of distribution are prescribed by the EFSP, but one can think of a final specification as a complete package that combines a read-only version of the specification document, technical artifacts (e.g. APIs), a TCK, and one or more compatible implementations. Again, the EFSP makes no specific requirements regarding how everything is packaged, so, for example, the TCK and compatible implementations may manifest as pointers.

The Specification Project Persists: A specification project is formed around the idea of producing and maintaining a specification in the general sense. The same specification project will produce multiple versions of a specification. After the final and complete version of a specification is released, the project team will begin the development cycle for the next release.

Members of the team (i.e. the committers and project Leads) may come and go, but the team remains.

A specification project has a well-defined scope that defines the boundaries of their activity. All versions of specifications produced by the project must fall within the scope.

The EFSP does not prescribe how resources associated with specification projects are structured, beyond a requirement that the specification project must be the home for the specification document. For technologies like Java® that have technical artifacts (e.g. interfaces) it is convenient, but not necessary to have the source for those technical artifacts maintained as part of the project.

Strictly speaking, a specification project can also be the home for a TCK and compatible implementation. As mentioned earlier, it is considered a best practice to keep compatible implementations separate (it may even be considered a bad practice to couple an implementation with the specification).

The Project Management Committee: Top-level projects are managed by a Project Management Committee (PMC). A PMC has one or more PMC leads and zero or more PMC members. Together the PMC provides oversight and overall leadership for the projects that fall under their top-level project.

Under the Eclipse Foundation Development Process (EDP) open source projects are organized hierarchically. A special type of project, top-level Projects, sit at the top of the hierarchy. Every top-level project contains one or more projects (which are sometime referred to as “subprojects”). As a general rule, top-level projects are primarily an organizational construct, and all real work occurs in subprojects.

Every top-level project has a PMC that supervises the projects under their purview to ensure that they are all working under the rules defined by the EDP, EFSP, and the Eclipse Foundation’s Intellectual Property Policy.

The Specification Committee: A committee of a working group established to manage the EFSP for technologies within the scope of its working group.

Open source projects are the means by which developers collaborate at the Eclipse Foundation. working groups are a means for companies to work together. The Jakarta EE Working Group, for example, brings companies together to collaborate on marketing, ecosystem development, governance, and (of course) open source software and specification development. As part of their governance activities, a working group must establish a specification committee to define and manage a specification process on behalf of the working group.

The specification committee is responsible for ensuring that that the specification teams keep within their defined scope, and generally ensure that the specification versions created by the specification project are implementable and serve the purposes of the working group.

Overview of the Process: the EFSP extends the EDP by adding a few extra checks and balances.

Each iteration through the development cycle starts with a plan. For the first iteration, the project proposal serves as the plan and the creation review as the approval.

Specification Project Proposal: Specification projects start with a proposal.

A project proposal describes the specification project that will be created. Proposals set out the scope and provide a description of the project and the specifications that the project will produce.

The Eclipse Foundation has a web form for defining project proposals. While a proposal is being drafted, the author and anybody designated as a project lead is able to edit the document. Everybody listed as an initial member of the specification team (i.e. committers) are able to view the document. The proposal becomes publicly accessible after it is opened for community review.

According to the EDP, the proposal must be open for community review for a minimum of two weeks to provide the community and key stakeholders to provide feedback and improve the proposal. The proposal can be modified during the community review period.

While open for community review, the EMO will investigate and approve trademarks associated with the project, which Eclipse Foundation holds on behalf of the project team and community. During this period the EMO will also work to get approval of other exceptions. This includes specification project licensing schemes that fall outside of the pre-approved licensing schemes for the top-level project.

When everything is in place (trademarks, licensing approval when required, identification of a mentor, and the minimum two week community review), the EMO will schedule a creation review.

Creation reviews run for a minimum of one week. The EMO schedules two review periods each month. Reviews are grouped together; they are scheduled according to their end dates which occur on the first and third Wednesdays of every month.

The proposal is locked down during the creation review period and no changes are possible. The creation review period is the last opportunity for the community and stakeholders to provide feedback. The specification committee and the membership-at-large of the Eclipse Foundation can intervene with the creation process. The membership can, should they find cause, request that the EMO fail a creation review and require that the proposal author either make additional changes and restart the review process, or withdraw the proposal completely (for what it’s worth, this has never happened).

Upon successful completion of the creation review, the Eclipse Foundation will engage in a provisioning process to turn the proposal into a live specification project. Provisioning starts with the authorization of committers which is initiated via email requests to all committers listed on the proposal to engage in our paperwork process. The provisioning process is kept on hold until the Eclipse Foundation’s records team has the necessary paperwork from at least one committer.

The proposal document serves as the plan for the first development iteration. Subsequent iterations through the process rely on the creation of a release plan and plan review.

Release Planning: The project team assembles the plan for each release cycle.

Again, note that the proposal and creation review serve as the plan and plan review for the first release.

The plan must be in-scope (i.e. all new work must fall within the bounds defined by the specification project’s scope) and must be developed in consideration of the concerns of stakeholders. It must, for example, take into consideration overarching plans of the PMC or associated working group. It’s worth noting that the concerns of the project team must also be taken into consideration when creating an overarching plan. We’re all in this together.

The plan is delivered to the specification committee via a plan review. The specification committee must vote to approve: a two-thirds majority of positive votes are required to succeed. How the individual members of the specification committee decide to vote varies; but at a minimum, by voting yes, members affirm that they believe that the planned work fits within the project’s scope and that sufficient consultation with the community and stakeholders has occurred.

All reviews, including plan reviews, run for a minimum of one week. They start with the delivery of review materials, and end with the conclusion of the voting period. For a plan review, materials include the plan itself along with a concise description (executive summary) of the plan. For progress and release reviews (which will be discussed shortly), the review materials include a milestone or release candidate build of the project content.

All reviews are run in the open. In addition to the approvals that are required, reviews offer an opportunity for the community and adopters to make their concerns known. As the entire process is run in the open, reviews should be considered as a final opportunity to express concern: parties who have a stake or interest in a specification process should engage early and often via project-specific open channels.

In the event that a review fails, the project team must regroup, incorporate feedback, and re-engage in a new review. The EFSP makes no requirement regarding the timing of re-engagement.

Committers Develop Specifications: Committers have the power and responsibility to push content into the specification project’s Git repositories. Committers hold most of the power and responsibility in the process.

Committer power must be used wisely. Committers have awesome power, but they also have awesome responsibility and are expected to work to the benefit of the community and ecosystem.

Committers Accept Contributions: Committers accept contributions from non-committers. In the GitHub world, this takes the form of committers reviewing and accepting pull requests.

Committers are responsible to ensure that the accepted content is within scope and release plan, and that the Eclipse Foundation’s Intellectual Property Policy is observed and the IP Due Diligence Process is followed.

Contributors must sign the Eclipse Contributor Agreement (ECA).

Technology Compatibility Kit (TCK): While the specification project committers are developing the specification resources, TCK project committers and contributors assemble the TCK.

The EFSP does not make any requirements regarding where the TCK lives. It may be a part of the corresponding specification project, or it may be separate.

When separate, a TCK project is a traditional Eclipse open source software project. Committers and contributors work on a Eclipse open source software project in much the same way they do on a specification project: committers can push directly to the project’s Git repositories, and must review and accept contributions from non-committer contributors.

Produce Milestone Builds: The project team will produce milestone builds.

A milestone build is a pre-release build of a version of the specification (“Specification Version”). Milestone builds are intended for a use only by a limited audience (generally the project team themselves, committers working on candidate compatible implementations, and other early adopters).

All efforts should be undertaken to ensure that a milestone build is technically correct, though it may be incomplete. A compatible implementation cannot be based on a milestone build of a Specification.

Later builds may be labeled as “release candidates”. For the purposes of the EFSP and EDP, the terms “release candidate” and “milestone’ are different only in intent.

Progress Review: The specification project team must engage in at least one progress review during their release cycle.

Progress reviews are a notion that is inherited from the EDP. The intent of a progress review is to ensure that the work is in-scope; that a project is making progress towards a release that will be approved; and that the EDP, EFSP, and Eclipse Foundation Intellectual Property Policy are being followed.

The project’s record of intellectual property contributions (IP Log) must be submitted to the EMO for review and approval before engaging in the review. Supporting materials for a review, including a concise description (executive summary) of the progress made to-date and a milestone build of the project content must be submitted before the start of the one week (minimum) review period. The progress review must be approved by simple +1 from a PMC representative, and by positive two-thirds super-majority vote of the specification committee.

Implementing the Specification: While the specification project’s committers work on the specification content, other teams may work on implementing them.

An implementation cannot be referred to as a compatible implementation until after the particular version of the specification is ratified and declared a final specification (and—of course—fulfills all of the requirements of the TCK associated with the final specification).

The EFSP makes no requirement regarding timing. In a code-first world, the implementation may exist before the specification. In this hypothetical case, an implementation project’s team would instead make refinements to their implementation based on the work-in-progress. It’s expected that implementation teams will interact regularly (via open channels) with the specification project’s team to provide feedback and ask questions.

In order to be declared final, a specification needs to have at least one compatible implementation that implements all aspects of the specification (including any optional parts) and released under one of the open source licenses listed in the EFSP (more below).

This introduces a bit of a “chicken and egg” problem: we can’t have a final specification without a compatible implementation and we can’t have a compatible implementation without a final specification. The specification project, TCK project, and implementation teams need to work together so that at least one implementation will be available and complete in time to be officially released and declared a compatible implementation at the time the final specification is ratified.

Release Review: The specification project team must engage in a release review at the end of their release cycle.

At least one compatible implementation must be distributed under one of the open source licenses specified by the EFSP: EPL-2.0, EDL-1.0 (BSD-3-Clause), Apache-2.0.

As is required for a progress review, the project’s record of intellectual property contributions (IP Log) must be submitted to the EMO for review and approval before engaging in the release review, the review must be approved by simple +1 from a PMC representative, and by positive two-thirds super-majority vote of the specification committee.

Following a successful release review the specification version transmogrifies into a final specification.

Final Specification: With the successful completion of a release review, including approval of the specification committee by a super-majority vote, a specification version is considered ratified and the associated artifacts are promoted and distributed by the specification committee as a final specification.

All versions of specifications that are referenced by a ratified final specification must themselves be ratified. The release review for related specification versions may be run concurrently.

Final Specification Licenses: Final Specifications and their associated artifacts are distributed under specific licenses.

The Specification Document for the Final Specification must be distributed as read-only text under the Eclipse Foundation Specification License. The Ratified TCK in composite is distributed under the Eclipse Foundation TCK License. Other technical artifacts must be distributed under an open source license (normally the specification project’s license).

Compatible Implementations: Implementations may only claim compatibility with a final specification.

As discussed earlier, there must exist at least one compatible implementation of a specification version under one of the designated open source licenses before it can be ratified as a final specification. Other compatible implementations may be created from the final specification and distributed under other licensing terms (as determined by respective vendors).

The intellectual property rights required to build a compatible implementation flow from the final specification. That is, in order to be considered a compatible implementation and benefit from the intellectual property protections provided by the Eclipse Foundation Specification Agreement, an implementation must be based on a final specification. No claims regarding compatibility may be made for an implementation milestone build or unratified specification version.