How to Prepare API Projects for the Jakarta EE 8 Release

1. Scan and make the following changes in javadocs and all text files such as (README.md, NOTICE.md, CONTRIBUTION.md, etc) in a repository
   1. Update project name as it listed on Eclipse project page (ex. Jakarta JSON Binding)
   2. Update acronyms, use new acronyms, approved by a spec committee (see guideline here).
   3. Update references to other specifications with their new names
   4. Leave existing "@since XYZ 1.x" uses alone. These refer to the old JCP version. Future additions should use the Jakarta project name.
   5. Remove references to JCP process or replace them with references to JESP.
      • Example: JSR-367 -> Jakarta JSON Binding
2. Generate the "boilerplate" specification document, using the instructions and recommendations provided in the Steering Committee guidance (The document is still under Steering Committee review, but projects are free to take the recommended actions immediately).
   • Use the same spec version number as the previously released spec
3. Make a staging release of API JAR from the revised source code.
   • Source code should use the new specification names and follow the acronym guidelines, and should remove any JSR references.
   • Javadocs should include the Eclipse Foundation Specification License.
   • Version in pom.xml should be increased by 0.0.1 comparing to the previously released API artifact
   • Existing "@version ..." JavaDoc tags should be updated to match, or removed.
   • GAVs should remain as used in the Glassfish 5.1 release. They should not be updated for changes in the project names. That will be addressed post Jakarta EE 8.
   • Dependencies should be using the GAVs that use the jakarta.* groupId.
4. Generate Stand-alone TCK test results. Use version staged on the previous step. There are some ways how to do it. Teams are free to choose any of them:
   1. Create custom TCK test job
      • Guidance is here.
      • Save the test results when all tests succeed.
   2. Manually run TCK by whatever means the project has used in the past. Save results when all tests succeed.
   3. Create a compatibility certification request for the compatible implementation being used to validate the spec in the specification repository issue tracker. If the project does not already have a compatibility-certification-request template, you can use this one: compatibility-certification-request.md
5. Generate Stand-alone TCK test results for a complete Compatible Implementation using one of the techniques above. For many projects, the Compatible Implementation will be Eclipse GlassFish 5.1. Note that the Compatible Implementation need not use the update API jar file, although it may.
6. When tests are passed, submit for ballot by creating PRs against the Jakarta Spec Committee Spec Repo
   • The project team creates two draft PRs against the Jakarta EE Specification Committee specifications repository.
   1. The first PR provides everything requested in the PR template except the javadoc contents.
   2. The second PR would include the javadoc contents.
      • These PRs are intended to provide the items that are required to validate the release, and provide the jakarta.ee website content for the specification. The repo has a PR template that lists the expected content for the PR. It includes:
        • A directory using the specification code as defined in Projects, Specifications, and Documents, e.g., wombat
        • A subdirectory major.minor corresponding to the version of the spec, (e.g., 1.6), that contains:
          • Specification Document from (2) above in both pdf and html formats, e.g., wombat_1.6.pdf and wombat_1.6.html
          • Summary results of TCK run showing at least one compatible implementation
          • Link to final TCK test bundle if the spec defines a TCK
            • Final version of standalone TCK bundles will be uploaded to Eclipse downloads
          • The URL of the OSSRH staging repository for the api, javadoc artifacts
          • An apidocs directory containing the final JavaDocs (from 3) in the second PR.
7. Update the Jakarta EE API jar by submitting a PR to the jakartaee-api project that updates the version number of your API jar file.
8. Update Eclipse GlassFish to use the new version of your API (and implementation, if applicable) by submitting a PR to GlassFish. (Although a new version of GlassFish will not be released for Jakarta EE 8, we hope to release an update sometime later.)
9. Create a release record as described in https://www.eclipse.org/projects/handbook/#pmi-commands-release
10. If a Release Review is required, perform the following steps. (A Release Review is not required if the current release is a Service Release based on a previously successful Major or Minor release as indicated by a release record on the project's Releases page, e.g., the Jakarta Servlet releases page. A Release Review will not be required for most of the Jakarta EE projects.)
    1. Request approval for the release from the PMC by sending an email to ee4j-pmc@eclipse.org referencing the release record.
    2. Deliver an IP Log to the IP Team for their review as described in https://www.eclipse.org/projects/handbook/#pmi-commands-iplog.
    3. Contact the EMO to initiate the release review by sending an email to emo@eclipse.org.
11. When approved
    • Release staged artifacts to Maven Central. Advice on this can be found here.
12. If (6) is accomplished prior to Ballot submission deadline (currently July 19) and Eclipse has released specification text to your project -- please feel free to start to generate a more detailed Jakarta EE specification, from the contributed specification text.