Jakarta Activation 2.0.1 (SR)

[lukasj]

Specification PR template

When creating a specification project release review, create PRs with the content defined as follows.

Include the following in the PR:

• A directory in the form wombat/x.y where x.y is the release major.minor version, and the directory contains the following.
  N/A
• Specification PDF in the form of jakarta-wombat-spec-x.y.pdf
  N/A
• Specification HTML in the form of jakarta-wombat-spec-x.y.html
  N/A
• A specification page named _index.md following the template at:
  https://github.com/jakartaee/specification-committee/blob/master/spec_page_template.md
  N/A
• 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.
  N/A
• For a Release Review, a summary 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.
  • Updated release record
  • Generated IP Log
  • Email to PMC
  • Start release review by emailing EMO
    N/A
• For a Service Release Review
  • Updated release record
    https://projects.eclipse.org/projects/ee4j.jaf/releases/2.0.1
  • Add Change Log
  • Start release review by emailing Specification Committee
• The URL of the OSSRH staging repository for the api, javadoc:
  https://jakarta.oss.sonatype.org/content/repositories/staging/jakarta/activation/jakarta.activation-api/2.0.1/
• The URL of the staging directory on downloads.eclipse.org for the proposed EFTL TCK binary:
  N/A
• The URL of the compatibility certification request issue:
  Compatibility certification request for EE4J implementation of Jakarta Activation 2.0.1 jaf-api#66
• Specification JavaDoc in the wombat/x.y/apidocs directory.
  If desired, an optional second PR can be created to contain just the JavaDoc in the apidocs directory.

Note: If any item does not apply, check it and mark N/A below it.

[lukasj]

@kwsutter let's go through this one to try out the simplified process. Let me know what needs to be adjusted. Thanks!

[netlify]

Deploy preview for jakartaee-specifications ready!

Built with commit 3797ab4

https://deploy-preview-336--jakartaee-specifications.netlify.app

[kwsutter]

@kwsutter let's go through this one to try out the simplified process. Let me know what needs to be adjusted. Thanks!

Hi @lukasj. Sounds good.

• One thing that is difficult to review are the actual changes to the javadoc. There is so much "noise" due to the year change from 2020 to 2021 that I can not easily find the meat of the proposed changes.
• I'm sure a similar situation will happen with the Spec unless change bars are used...
• Maybe we need something to document what's being done via this Service Release. Maybe you have this documented somewhere and we just need a reference?
• I think you still want to reference an Eclipse Release Record: https://projects.eclipse.org/projects/ee4j.jaf/releases/2.0.1
• Everything else looks good!

I was thinking that maybe we need a condensed checklist, but each service release will be different. Some may be updates to the Spec document, the javadoc, the tck, the CI, or any of the above. So, I suppose the checklist needs to stay long and let each service release determine which parts apply. Agree?

Thanks!

[lukasj]

• One thing that is difficult to review are the actual changes to the javadoc.

Cp year change unfortunately cannot be avoided, I think. Other than that there are two changes in javadoc:

• added API version there (based on Jakarta Activation 2.0 Draft apidocs #217 (review))
• added pointer to project's mailing list in the footer

• Maybe we need something to document what's being done via this Service Release. Maybe you have this documented somewhere and we just need a reference?

You mean change log? The only "real" change here is the fix for jakartaee/jaf-api#53 (hence just a small note with no particular pointer in the release record)

• I think you still want to reference an Eclipse Release Record: https://projects.eclipse.org/projects/ee4j.jaf/releases/2.0.1
• Everything else looks good!

I was thinking that maybe we need a condensed checklist, but each service release will be different. Some may be updates to the Spec document, the javadoc, the tck, the CI, or any of the above. So, I suppose the checklist needs to stay long and let each service release determine which parts apply. Agree?

Probably adding a point for Service Release with checkboxes for release record and emailing spec list would make sense. WDYT?

[lukasj]

I've put what I mean to PR description

[kwsutter]

I've put what I mean to PR description

I like that update. We'll have to update the template to get that in.

I still think we need something to describe the service release content. Should we put that in the index.md file? Or, should it be in the Eclipse Release Record? Maybe the latter... Looking for input since you're the first one through the gate... Thanks!

(Also, sorry for the delay in responding, but I'm on a part-time schedule and I'm off on Fridays and Mondays. And, I missed your update last Thursday before I left for the weekend. My apologies.)

[lukasj]

I like that update. We'll have to update the template to get that in.

what about having 2-3 different templates having only relevant content? There could be even completely different template for ie plan reviews etc. See ie what Bill did in jaf - it would be nice to just pick up template matching my intent

I still think we need something to describe the service release content.

I think that the spec page itself is the best place, I've tried to add simple changelog here to see how it looks. I do not think it is the right place for "invisible" changes as there is a space for them in the release record itself.

And when we are at the release record - which one should the main/first link be pointing to? The one for initial version (2.0) as it is now, or should it be updated to the latest one (2.0.1)?

[kwsutter]

I like that update. We'll have to update the template to get that in.

what about having 2-3 different templates having only relevant content? There could be even completely different template for ie plan reviews etc. See ie what Bill did in jaf - it would be nice to just pick up template matching my intent

The only bad thing about having multiple templates is that there is so much duplication. If you change one, you may have to change many or all of the others when there is a lot of duplication. But, we can definitely consider that approach.

[kwsutter]

I still think we need something to describe the service release content.

I think that the spec page itself is the best place, I've tried to add simple changelog here to see how it looks. I do not think it is the right place for "invisible" changes as there is a space for them in the release record itself.

And when we are at the release record - which one should the main/first link be pointing to? The one for initial version (2.0) as it is now, or should it be updated to the latest one (2.0.1)?

The specifications page (the one you called the main/first link) needs to point at the 2.0 release record. From a Specification version perspective, we are only interested in major and minor versions. So, that's why the main page should not be pointing at a service release.

I kind of like your changelog idea. This extra file would only be required when service releases are introduced since other releases would be covered by a release plan. Would you find this type of requirement difficult or livable?

[lukasj]

I kind of like your changelog idea. This extra file would only be required when service releases are introduced since other releases would be covered by a release plan. Would you find this type of requirement difficult or livable?

well, it's almost like Java itself - "write once, paste everywhere" - sort of thing, so to say :-D I think having a change log directly on the spec page is a good thing, nobody wants to go through X pointers to get to know main differences and even JCP has been requiring it (see ie jsr222). As long as it can be kept simpler than for JCP (ie just a free-form text file with no or very simple template) and other places, like the required release record or github release can have just a pointers to this, I'm fine with it.

[lukasj]

The only bad thing about having multiple templates is that there is so much duplication.

I agree with you here. It's about finding the right balance between maintenance cost of templates and ease of submission process. Unfortunately it is unlikely both can win this battle.

[lukasj]

I could address also parts of #318 (for jaxb) but that would mean also new version of the spec document. Or is that something to be fixed globally in existing documents without updating spec version number and probably just increasing revision number there?

[kwsutter]

I'm good with this. @ivargrimstad? We can modify the template for the Issues. I also like the reference to the separate ./changelog file.

[kwsutter]

Created PR #345 for updating service release PR template based on the discussions in this PR and the Mail PR #339.

[kwsutter]

Since @ivargrimstad already approved and merged the Jakarta Mail PR #339, and I received his "verbal" approval yesterday via Slack, and Activation is a prereq for Mail, I'm going to go ahead and merge this PR as well. :-)

[kwsutter]

Thanks again, @lukasj, for working with us as we figured out this Service Release process! Much appreciated! Not only your patience, but your input on what works and what doesn't. Thank you!