Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Spec: Todo #804

mkarg opened this issue Oct 23, 2019 · 2 comments


Copy link

@mkarg mkarg commented Oct 23, 2019

This issue serves as an aggregated placeholder for the open TODOs with the Spec document, so we can organize to work in parallel without solving problems twice. The following list shows the open issues. If you like to provide a solution for one of these issues, please post a comment below.

  • (@chkal: #801) Initial contribution of the spec asciidoc "as-is" to master
  • (@mkarg: #801) URL fixes
  • (@mkarg: #801) Maven Coordinates
  • (@mkarg: #806) Java EE -> Jakarta EE
  • (@mkarg: #802) Can also build spec on JDK 9 and later now
  • (@mkarg: #802) Travis CI/CD builds spec
  • (@mkarg: #806) 2.x -> 2.2-SNAPSHOT
  • POM Cleanup. Maybe drop assembly?
  • (@mkarg: #806) Changes mentioned in CQ 20980: During our initial review of this submission, we noted that the source code headers are either incorrect or missing. As this is a housekeeping issue only, you may proceed with checkin, however we would ask that the correct copyright and license headers be added to the files per Eclipse standards. Please ensure that this is done and notify us via the CQ once this is completed. -- @ivargrimstad triggered @waynebeaton to provide the wanted copyright header template.
  • Publish nightly build of snapshot PDFs/HTMLs
  • Modifying references to the JCP with corresponding Eclipse processes.
  • What do we do with references to JSRs? [EJB] Use spec. Name and version number of the specification instead.
  • References to existing Java EE technologies, acronyms, and JSRs are okay as long as they are properly attributed.
  • Be careful not to modify the semantics or behavior — we need Jakarta EE 8 to be functionally equivalent to Java EE 8.
  • (@mkarg: #806) Use the original Java EE specification as a guide for your expected end result. Look at the TOC, the figures, the tables, the indentations, etc. The Jakarta EE specification should look very similar to the Java EE counterpart.
  • (@mkarg: #806) Continue to use the general template and format that the skeletal specifications are using. For example, use a top-level asciidoc file that defines the overall configuration parameters and includes the other sections of the specification document. The front page, table of contents, and license should all be very similar to the skeletal specifications that were approved for Jakarta EE 8.
  • (@mkarg: #807) Split up huge asciidoc into chapters. For most skeletal specifications, the “scope.adoc” file should be replaced with the newly contributed asciidoc version of the specification. Consider breaking down this specification asciidoc file into individual chapter sections if it’s large and you expect multiple people to contribute to this effort. The Platform and Web Profile Specifications are examples of this content break down. Look at Platform.adoc and/or WebProfile.adoc.
  • (@mkarg: #806) Remove Oracle Copyright statements. They should be replaced with “Copyright © 2019 Eclipse Foundation” (per the skeletal specification).
  • (@mkarg: N/A - apparently already correct) All internal document linkrefs need to be re-worked.
    • Original:
      link:WebProfile.html#a43[See Required Components].
    • Updated:
      <<a43, Required Components>>.
    • Suggest using regedit replacement macros if you have many to change. If just a few, then manual edits are fine.
  • (@mkarg: N/A -- apparently already correct) The links need to be on a separate line from the headings.
    • Original:
      == [[a2845]]Interoperability
    • Updated:
    == Interoperability
  • Again, using regedit replacement macros makes this type of change easier if you have many to change.
  • Use “https://” instead of “http://” for any external links.
  • (@mkarg: TBA) Ensure that external specification links are now pointing at the respective Jakarta EE Specification page (and not the Java EE specifications). ™ does not work for ™ ; use “(tm)”. See more about textual symbol replacements.
  • (@mkarg: N/A - already just three levels) Sub sections of document beyond three indentation levels (1.2.3) didn’t format very nicely. You may need to visually ensure that the proper indentation levels match up with the original specification expectations. Limit the TOC to three levels (:toclevels: 3)
  • (@mkarg: N/A - apparently already correct) Inserting images has a different syntax:
    • Original:
      Jakarta EE Application Life Cycle image:Platform_Spec-10.png[image]
    • Updated:
      .Jakarta EE Application Life Cycle (note the leading period) image::Platform_Spec-10.png[]
  • (@mkarg: N/A - apparently already correct) Tables didn’t migrate well at all… When you find a table, start off with this type of header and then insert the data on each new line. Here’s an example…
[cols=3, options=header]
.Deployment Descriptor Processing Requirements
|Deployment descriptor
|process annotations?

  • (@mkarg: N/A - already used) [appendix] is a handy element if your specification had them in the past
  • (@mkarg: N/A - looks good as-is) Footnotes were kind of ugly. Getting footnotes to render in a similar manner for both pdf and html generation was tricky. I ended up using the following syntax:
  • footnote:[text of footnote]  — get text from the [.footnoteNumber] items
  • Remove all of the “[.footnoteNumber]…​” items from the migrated document. They are no longer needed.
  • Add a dividing line at the bottom of each page where footnotes will reside via three single backward quotes (`). Reference this PR for an example.
  • (@mkarg: #806) Formatting code blocks needs work as well. Surround code block in ---- (4 dashes). Add [source, java] or [source, xml] as needed. More specific detailed help can be found in this PR

  • Bug: Resource matching: algorithm looks rather weirdly formatted

  • Bug: "Filters and Interceptors / Introduction": There are four... and then there are commas without words. Same at "Filters": " ...namely:... and then there are commas without text.

  • (@mkarg: #808) Enhancement: Fail build on error.

Tip: The Asciidoctor Editor plug-in provides a solid set of tools for authoring Asciidoc files in the Eclipse IDE; versions of this plug-in exist for other IDEs as well.

Thanks to @chkal and @ivargrimstad ( for their issue lists! :-)

@mkarg mkarg added the spec label Oct 23, 2019
@mkarg mkarg added this to the 2.2 milestone Oct 23, 2019
@mkarg mkarg assigned chkal and mkarg Oct 23, 2019

This comment has been minimized.

Copy link
Member Author

@mkarg mkarg commented Oct 23, 2019

@chkal Self-service spec assignment roster is opened hereby. ;-)


This comment has been minimized.

Copy link
Member Author

@mkarg mkarg commented Oct 28, 2019

WARNING The huge asciidoc file was split into single file per chapter in PR #806. That PR is not merged into master yet. So before starting to work on the spec, please always:

  • fetch PR #806
  • rebase ontop of the chapter splitup, or cherry-pick the two chapter-split commits.

Otherwise you will have big trouble when pushing your changes due to lots of conflicts!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
2 participants
You can’t perform that action at this time.