This document describes the practices of the Jakarta EE Specification
Changes to this document must be approved by a simple majority vote of
the Jakarta EE specification committee, conducted via the public Jakarta
EE Specification Committee (email@example.com) mailing list.
This is a public document.
The Jakarta EE Specification Committee is responsible for implementing
the Eclipse Foundation Specification Process (EFSP) for all
Specification Projects (as that term is defined by the EFSP) under the
purview of the Jakarta EE Working Group. This includes the adaptation of
the EFSP for Jakarta which is referred to as the Jakarta EE
Specification Process (JESP).
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
wields 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
The Specification Committee 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/JESP for those Specification
Projects under their purview.
Project Management Committee (PMC)
The primary role of the PMC is to ensure that project teams are
implementing the Eclipse Development Process. 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 abiding
by the Eclipse IP Policy and implementing 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
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) Designation
A specification project must designate one or more committers to serve
as the project lead. The lead is responsible for initiating reviews as
the project reaches the appropriate milestone.
Specification Committee Votes
Specification committee approval votes connected to progress and release
reviews run for a minimum of 14 days; other votes run for a minimum of 7
The requirements for each are described in Review
The standard release
process defined in
the Eclipse Foundation Project Handbook is followed and augmented with a
specification committee ballot. Additional detail for the various
reviews can be found in these sections:
The Specification Committee Chair (or their delegate) initiates a specification committee ballot by sending an email
on the public Jakarta EE Specification Committee
(firstname.lastname@example.org) mailing list that describes the nature
of the vote (creation/progress/release) and includes pointers to the PR
request containing the proposed release content (e.g. release review
document, specification document, and technical artifacts).
A specification committee member votes by responding to the ballot
message on the public Jakarta EE Specification Committee mailing list,
using the usual +1/0/-1 voting notation.
If a specification committee member votes against a motion, they must
provide a comment that explains the reason for the negative vote and
suggest steps to mitigate the issue.
The specification committee chair (or their delegate) tallies the
results of the vote, and aggregates the comments and presents them to
the community via the specification project page on jakarta.ee, a
summary email to
email@example.com and firstname.lastname@example.org, within one week of
the completion of the vote.
The specification committee may choose to extend the deadline for a vote
by simple majority vote on the public specification committee mailing
In the event that a vote fails, the Specification Committee Chair (or their delegate) will fail the corresponding
review, forward the comments from the vote to the specification team,
and invite them to resolve the issues and re-engage at a later date.
Note that the EMO schedules reviews to conclude on the first and third
Wednesday of the month; this will impact the timing of the start of a
specification committee vote and the timing of a project team
re-engaging following a failed vote. This means that specification
committee chair must start the vote at least 14 days prior to the first
and third Wednesday of the next month if they wish to minimize the time
for the review to complete. In the event that the specification
committee opts to extend a vote, the EMO will, at its discretion, either
bump the corresponding review to the next review slot or withhold
approval of the review until the results of the specification committee
vote are received.
Participant Representative Appointments
A Member Participant may send a note to email@example.com to designate
or remove their representative (a Member Participant’s representative
must be covered by the Member Company’s MCCA and WGPA) as the
Participant Representative (and Committer) for the Member Participant on
any specification project associated with the Jakarta EE Working Group.
The EMO will maintain a record of participant representatives on the
specification project’s PMI "Who’s Involved" page in a section titled
"Participant Representatives" (e.g. Eclipse Project for Servlets
A Jakarta Specification is developed by a Specification Project.
The Eclipse Development Process is followed, with a few additions.
The following steps are required in order to start a new specification project:
- Create a Project Proposal (*)
- Inform the Specification Committee with a mail on the public mailing list (*)
- When the specification project has been approved by the Specification Committee by vote on the mailing list and creation review completed successfully by the EMO, create a Pull Request to be listed as a Jakarta EE Specification. The PR must contain an
_index.md file located in a folder named after the short name of the specification. Here is an example of Jakarta MVC. The _index.md is located in the mvc folder in the Jakarta EE Specifications GitHub repository.
title: "Jakarta MVC"
summary: "Jakarta MVC defines a standard for creating web applications following the action-based model-view-controller pattern."
summary60Char: "Jakarta MVC standardizes the action-based MVC pattern."
Model-View-Controller, or MVC for short, is a common pattern in Web frameworks where it is used predominantly to build HTML applications. The model refers to the application’s data, the view to the application’s data presentation and the controller to the part of the system responsible for managing input, updating models and producing output.
Web UI frameworks can be categorized as action-based or component-based. In an action-based framework, HTTP requests are routed to controllers where they are turned into actions by application code; in a component-based framework, HTTP requests are grouped and typically handled by framework components with little or no interaction from application code. In other words, in a component-based framework, the majority of the controller logic is provided by the framework instead of the application.
(*) 1 and 2 may be done in any order. In fact, it may be a good idea to socialize the idea with the Specification Committee before proceeding with the project creation.
Specification projects in active development must engage in a progress
or release review at least once per year as required by the JESP. 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
Creating a Release Plan
Each specification project needs to engage in a Plan Review prior to any
extensive development effort in support of a new Specification Version.
A simple Release Plan may be defined via an Eclipse release
A more extensive Release Plan may be easier to define via an external
document. If an external document is created, it should be referenced in
the Eclipse release record. That is, an Eclipse release record is
required regardless of where the detail for the release is documented.
If an external Release Plan is developed, it needs to be made available
via the Specification Project’s web pages. As an example, the Jakarta EE
9 Release Plan is housed on the Platform Project’s github
The Release Plan should be reviewed with the Specification Committee
before continuing with the ballot stage.
Recommended Specification Project Repository Structure
The current recommendation for structure of the specification project
repository is to have one *-spec repository with an api and spec
subdirectory for the API and specification content, and a second *-tck
repository for the TCK content.
Each specification project has a location on the jakarta.ee website
For each final specification:
Links to specification documentation and all related artifacts
including the TCK and compatible implementations that will be
updated as new implementation are certified;
Metadata, including version number and date of release
Results of all specification committee votes
Creating a Final Specification
A specification document that is marked "Final" cannot be made
generally available until after engaging in a successful release review
(with corresponding super-majority approval from the specification
Note: A "Final" service release (x.y.z) specification has an abbreviated approval process.
Although a release review is not required, several of the following requirements will still apply for a service release.
A release review will have validated that the specification
Produced a final staging release via OSSRH staging repository for the api,
Javadocs should include the Eclipse Foundation Specification
Version in pom.xml should be increased by comparing to the
previously released API artifact.
Existing "@version …" JavaDoc tags should be updated to
match, or removed.
The candidate final EFTL
licensed TCK archive should be uploaded to the project directory
under http://download.eclipse.org/ee4j, e.g.,
Generate standalone TCK results or platform TCK result as
appropriate for the spec project.
Create a compatibility certification request for the compatible
implementation being used to validate the spec in the specification
repository issue tracker (as appropriate). If the project does not already have a
compatibility-certification-request template, you can use this one:
Initiate a Specification review request by creating
(also assign the
draft label) against the Jakarta EE Specification Committee
repository. These draft PRs provide everything as requested in the PR
As an aid in the final review process, the Specification Review Checklist should be added to the Specification PR.
If this updated Specification Version is targeted for the Platform, update the Jakarta EE API jar by submitting a PR to the
project that updates the version number of your API jar file.
If this updated Specification Version is targeted for the Platform, update Eclipse GlassFish to use the new version of your API (and
implementation, if applicable) by submitting a PR to
Create a release
record (if one doesn’t already exist) as described in the Eclipse
Request approval for the release from the PMC by sending an
email to firstname.lastname@example.org referencing the release record.
Deliver an IP Log to the IP Team for their review as described
in the Eclipse Project
After the PRs are sufficiently reviewed and approved, contact the EMO to
initiate the official release review ballot by sending an email to
ballot labels should be added to the PRs (removing the
draft label, if it exists).
When the ballot request PRs are approved, the Specification Project releases the staged artifacts
to Maven Central. Advice on this can be found in this
A specification committee member adds a comment on the main PR with the “ballot completion” section of this checklist.
approved label is added to both PRs (leaving the
The Specification Version TCK needs to be promoted by a member of the specification committee. Advice on this process can be found in this TCK promotion README.
After the release review has completed successfully, the Specification Version PR needs to be updated with the official ballot results by either the EMO or the specification committee.
The ballot update can be performed either on the original PR or a subsequent PR, whichever is most efficient.
The specification committee will promote the specification project to jakarta.ee by merging the associated PRs into the Jakarta EE Specifications project repository.
Creating a Final Service Release Specification
There is no formal release review required for a Specification service release (x.y.z) as long as the JESP definition of a “service release” is adhered to.
That is, no functionality changes or increase in IP scope are permitted in a service release.
Although much of the content of the Final Specification still applies, the approval process is simplified for a service release.
The creation and staging of the various artifacts (Specification, API, and/or TCK) are still performed via the initial steps 1 and 2 outlined above.
The creation of Specification PRs in step 5 is also required.
The Specification Project team should then send a note to the public Specification Committee mailing list announcing that the PRs are ready for review.
After the Specification PRs are reviewed and approved by independent specification committee members, the PRs can be merged.
The Specification Project team can then release the staged artifacts to Maven Central.
The EMO validates:
That the review material meets a minimum standard (meaningful
That the project repository includes the required legal
That the Eclipse Intellectual Property Due Diligence process has
The PMC validates:
That the Eclipse Development Process has been followed;
That the project is operating in an open and transparent manner;
That the specification document is consistent with established
That the project has no unreasonable barriers for participation;
That the submission material is complete.
The Specification Committee validates:
That the content presented for review is in scope;
That the website documentation adequately and consistently describes
That the specification document is consistent with established
conventions and meets the necessary quality standards.
For a Plan Review, a sufficiently detailed and doable Release Plan
has been created. In addition, an Eclipse release
exists that describes the content for the given release. This
description could be a reference to an external plan document.
For a Progress Review, that sufficient progress has been made on a
Compatible Implementation and TCK, to ensure that the spec is
implementable and testable.
For a Release Review, that a Compatible Implementation is complete,
passes the TCK, and that the TCK includes sufficient coverage of the
specification. The TCK users guide MUST include the instructions to
run the compatible implementations used to validate the release.
Instructions MAY be by reference.
The maven group id, artifact id, and artifact names should follow the
rules described in the
All new classes, as well as modifications to
javax. classes, are
created in the
This also applies to OSGi bundles produced by the project.
Petition the specification committee to request an exception to the
namespace rules above.
Where feasible, all source content must include a valid copyright and
license header. Tools such as the
be useful in ensuring consistency.
Specification Document Conventions (Currently under discussion)
Written in the third person tense
TBD "uses" vs. "includes"
Recommended formats, in order of preference: asciidoc, markdown, text.
The first reference to other specifications must use the official full
name. Subsequent references may use a generally accepted abbreviation.
Initial Migration Tasks
The requirements for the initial migration from the legacy Java EE
projects and associated naming conventions to the Jakarta conventions is
outlined in these documents:
Using these conventions, projects need to:
Change the specification name to that given in Project Names and
JavaDocs and text documents such as README files need to be updated
to use these naming conventions.
Replace references to JCP process with references to Eclipse
Update references to other specifications to use name in Project
Names and Codes
Links to JCP JSR pages need to be replaced with a links of the form
jakarta.ee/specifications/<code>/<version> where <code> is the
specification code from Project Names and Codes, and
<version> is the particular specification version.
Leave existing "@since XYZ 1.x" uses alone. These refer to the
old JCP version. Future additions should use the Jakarta project
Specification projects need issue templates and labels to support the
TCK challenge process, and the compatibility request process. Creating
an issue template is described in this GitHub doc:
Creating labels is described in this GitHub doc:
The current TCK challenge and compatibility request process requires the
following issue labels, which should be defined in the issue tracker:
||Accepted certification request
||Appeal a rejected TCK challenge
||TCK challenge was appealed
||Compatibility certification request s
||This doesn’t seem right (label already exists)
||New feature or request (label already exists)
Finally, follow How to Prepare API Projects to Jakarta EE 8
to create an initial Jakarta EE 8 release.