Enterprise Beans 4.0 Plan Review

[dblevins]

(all text revised as of Tue Feb 4)

The current state of this PR is still solidly 'draft' as we have a few things to discuss.

First, see this page for a draft of the proposed text for the detailed plan. This is in PR form:

• https://github.com/eclipse-ee4j/ejb-api/blob/053b5ceb50b5b3c63dd99f0adf568038045f0a83/4.0-PLAN.adoc#jakarta-enterprise-beans-40
• Draft of the Jakarta Enterprise Beans 4.0 plan enterprise-beans#64

Open discussion item on if this is an acceptable place for a plan to live. There is an open bug requesting a Github Pages setup:

• https://bugs.eclipse.org/bugs/show_bug.cgi?id=559668

Second, I still feel we need executive summaries on our specification pages. Understood we do not want detailed plans there, however there needs to be a one or two paragraph max executive-level overview so people do not need to read these 620 and 1600 word plans we're writing just to get an idea of what to expect.

[netlify]

Deploy preview for jakartaee-specifications ready!

Built with commit 70b2c64

https://deploy-preview-136--jakartaee-specifications.netlify.com

[dblevins]

Let's leave this open for feedback till Friday, January 31st 11pm Pacific. Given no ongoing discussion I suggest we assign to the Specification Chair @paulbuck to have ballots initiated.

[bshannon]

This text doesn't belong in the Pull Request, it belongs in the Release Plan for the Enterprise Beans project.

[smillidge]

I honestly thought there were more changes than that given all the debate on EJB in the Jakarta EE 9 release plan discussions.

[dblevins]

We need to have a conversation on the "plan shouldn't be in the _index.md" notion. My understanding is we were always aiming at this page being an executive summary of the expected changes/focus for a version similar to a JSR page. We appear to have diverged somewhere, so I'd like to figure how when that was.

[kwsutter]

We need to have a conversation on the "plan shouldn't be in the _index.md" notion. My understanding is we were always aiming at this page being an executive summary of the expected changes/focus for a version similar to a JSR page. We appear to have diverged somewhere, so I'd like to figure how when that was.

David, we've been on this Release Record idea for quite some time. I don't believe we have ever discussed updating the _index.md file with the proposed release plan. In some cases, that could get rather lengthy and cumbersome, and it would complicate the simplicity of this goto page. The process we decided upon was to document the proposed release plan via the Project's Release Records. If it becomes lengthy, then a separate document can be referenced in the Release Record like we did for the Jakarta EE 9 Release Plan.

I also documented this approach as the first bullet in the checklist in the Epic Issues I created for all of the Specification Projects:

• Create Eclipse Release Record in your respective Jakarta Specification Project.
  Most Component Release Records will just reference the Jakarta EE 9 Platform Release Plan. But, if your Component deviates at all from the Platform Release Plan, then a description of the changes will be required in the Release Record.

HTH,
Kevin

[bshannon]

We need to have a conversation on the "plan shouldn't be in the _index.md" notion. My understanding is we were always aiming at this page being an executive summary of the expected changes/focus for a version similar to a JSR page. We appear to have diverged somewhere, so I'd like to figure how when that was.

I believe the _index.md should describe the current state, not a "diff" from the previous state.
A key feature of the current state might be removal of a feature or API.

[dblevins]

I've updated the description in the PR and PR itself. There's a handful of things we'll likely want to discuss. In particular, what is the right kind of description we want to have for the specification page. I had always imagined we'd have an executive summary of the plan aside from our detailed plans. This revision and new separate plan is hopefully closer to something we can all agree on.

I'd love to talk about what is the right tex we imagine for an executive summary that can serve these goals:

• Enough to give the world a rough idea and facilitate a plan review
• Be understood to be a rough summary only updated at plan and via an occasional progress review or eventual release review.
• Allow the world to see the whole elephant without making them eat the whole elephant (read every detailed plan)

When I say one or two paragraph executive summary, we shouldn't just imagine casual observers, but ourselves 10 years out when we can't remember in what version of a spec we "did that thing."

Ideally, remembering when we "did that thing" will be harder over the next 10 years because we're releasing at least every year. None of us will want to follow 10 links and read 10 complete plans.

[kwsutter]

A couple of minor updates that should be corrected. Thanks!

[kwsutter]

I've updated the description in the PR and PR itself.

The abbreviated form of this description here looks acceptable. And, providing the links to the more detail is good. Thanks.

[kwsutter]

Found a syntax issue with a link in your text. We need to correct that before merging.

[dblevins]

When jakartaee/enterprise-beans#65 is merged, this plan should be good to go.

[dblevins]

@bshannon @kwsutter I think all the feedback has been resolved. If you can do a re-review and confirm, I think we can put this up for vote.

All 4.0 plan changes have been merged on the Jakarta Enterprise side of the fence.

@starksm64 @smillidge @kazumura Approvals from you guys will help signal if we are ready to vote.

[kwsutter]

Looks very good, @dblevins! Thanks!

[bshannon]

One minor comment, but otherwise looks good to me.

[bshannon]

If this isn't planned to be GlassFish, that would be good to know now,
since it would effect our platform release plans.

[kwsutter]

Since these changes look good and have been approved, I'll go ahead with the merge to clean up this older PR. I'm sure we'll need to adjust the content when EJB 4.0 becomes real... Thanks!