[WIP] Begin a specification release review checklist #193
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| ## 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 <project-name>/x.y where <project-name> is the specificaiton project name | ||
| (micropfile-config, microprofile-health, ...) and x.y is the release major.minor version, and the directory contains the following. | ||
| - [ ] Specification PDF in the form of microprofile-project-spec-x.y.pdf where | ||
starksm64 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| _project_ is the microprofile specification short project name (config, health, ...) | ||
| - [ ] Specification HTML in the form of microprofile-project-spec-x.y.html | ||
|
There was a problem hiding this comment. See the updated content |
||
| - [ ] A specification page named index.fmt in a TBD format. | ||
| - [ ] 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](https://www.eclipse.org/projects/handbook/#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 | ||
|
There was a problem hiding this comment. What do you mean by updated release record? There was a problem hiding this comment. 1, that it exists, and 2, that it has the correct date. The date determines when it can be scheduled for a review in the bi-weekly EMO release approval meetings. |
||
| - [ ] Generated IP Log | ||
|
There was a problem hiding this comment. Since MP is under one project, generating IP Log covers all projects. There will be massive duplication of IP Log for each included specs. In the past, only umbrella release generate IP Log. There was a problem hiding this comment. For a platform spec that is true. If you are generating a non-platform release of a spec, then that is not true. We'll probably have to figure that out when it is needed. |
||
| - [ ] Email to PMC | ||
| - [ ] Start release review by emailing EMO | ||
| - [ ] The URL of the OSSRH staging repository for the api, javadoc: | ||
|
There was a problem hiding this comment. I think you might have taken the Jakarta EE format. Since MP specs have api, tck under the same roof, you can delete the following line about tck and amend this line to include tck as well. There was a problem hiding this comment. This has been simplified |
||
| <add URL here> | ||
| - [ ] The URL of the staging directory on downloads.eclipse.org for the proposed EFTL TCK binary: | ||
| <add URL here> | ||
| - [ ] The URL of the compatibility certification request issue: | ||
| <add URL here> | ||
| - [ ] Specification JavaDoc in the <project-name>/x.y/apidocs directory. | ||
|
There was a problem hiding this comment. JavaDoc in the -version/apidocs. See https://download.eclipse.org/microprofile/microprofile-fault-tolerance-2.0/apidocs/ There was a problem hiding this comment. Can you move the javadoc together with spec pdf and html as they are all under the directory? There was a problem hiding this comment. See the updated format of the issue template |
||
| 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. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| # Spec Review Checklist | ||
|
There was a problem hiding this comment. Is this checklist file still in play? If so, there are several changes to modify the "jakarta ee" references to "microprofile". If not, then we should just remove it. |
||
|
|
||
| 1. Spec PR | ||
| - [ ] PR uses [template](https://github.com/jakartaee/specifications/blob/master/pull_request_template.md) | ||
| - [ ] Directory of form {spec}/x.y | ||
| - [ ] PDF of form {spec}-spec-x.y.pdf ("-spec" preferred but not required) | ||
| - [ ] HTML of form {spec}-spec-x.y.html ("-spec" preferred but not required) | ||
| - [ ] Index page {spec}/x.y/_index.md following (TBD) [template](https://github.com/eclipse/microprofile/blob/master/spec/spec_page_template.md) | ||
| - [ ] Staging repository link of the form | ||
|
There was a problem hiding this comment. Staging repo format should be https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-xxx/, e.g. https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1351/ |
||
| https://oss.sonatype.org/#nexus-search;gav~org.eclipse.microprofile.{spec}~microprofile-{spec}-api~~~~kw,version | ||
| - [ ] EFTL TCK link of the form http://download.eclipse.org/microprofile/microprofile-{spec}-{version}/+.zip | ||
|
There was a problem hiding this comment. TCK zip is not under download site. It is in sonatype. |
||
| - [ ] Compatibility certification link of the form https://github.com/eclipse/microprofile-{spec}/#{issue} | ||
|
There was a problem hiding this comment. Do you mean create a new issue to log TCK certification? |
||
|
|
||
| 2. _index.md | ||
| - [ ] Link to spec pdf | ||
| - [ ] Link to spec html | ||
| - [ ] Link to apidocs | ||
| - [ ] Link to final TCK download zip file of the form http://download.eclipse.org/microprofile/microprofile-{spec}-{version}/*{spec}-tck-x.y.z.zip | ||
|
There was a problem hiding this comment. The link is incorrect. TCK zip does not live under this site. There was a problem hiding this comment. Once we release, the tck zip will go to maven central. |
||
| - [ ] Link to API jar file of the form https://search.maven.org/artifact/microprofile.{spec}/microprofile.{spec}-api/x.y.z/jar | ||
| - [ ] Name of and link to at least one Compatible Implementation | ||
|
|
||
| 3. javadocs | ||
| - [ ] Footer contains Eclipse copyright and link to license | ||
| - [ ] ESFL license is included, usually as doc-files/speclicense.html | ||
| - [ ] no META-INF directory in PR | ||
| - [ ] javadocs-jar artifact matches apidocs | ||
|
|
||
| 4. Spec PDF | ||
| - [ ] Correct spec title | ||
| - [ ] Version number of the form x.y, not x.y.z | ||
| - [ ] Correct Eclipse copyright line | ||
| - [ ] No DRAFT or SNAPSHOT | ||
| - [ ] Correct Logo | ||
|
|
||
| 5. Spec HTML | ||
| - [ ] Same as PDF | ||
|
|
||
| 6. TCK zip file | ||
| - [ ] README file (optional for this release) | ||
| - [ ] EFTL license file, preferably named LICENSE.md | ||
| - [ ] User's Guide (or equivalent documentation) | ||
| - [ ] How to test the Compatible Implementation(s) listed in _index.md above with the TCK (may be in UG) | ||
|
|
||
| 7. TCK User's Guide (or equivalent documentation) | ||
| - [ ] Software requirements listed | ||
| - [ ] Installation and configuration described | ||
| - [ ] How to run tests | ||
| - [ ] Where to file challenges | ||
|
|
||
| 8. Compatibility certification request | ||
| - [ ] Request follows [template](https://github.com/jakartaee/specification-committee/blob/master/compatibility-certification-request.md) | ||
| - [ ] SHA-256 fingerprint matches staged TCK zip file | ||
| - [ ] Request issue has `certification` label. | ||
|
|
||
| 9. TCK results summary | ||
| - [ ] Page is hosted by Compatible Implementation project | ||
| - [ ] Includes all information from certification request | ||
| - [ ] Summary includes number of tests passed, failed, errors | ||
| - [ ] SHA-256 fingerprint matches staged TCK zip file on cert request | ||
|
|
||
| 10. EMO/PMC tasks | ||
| - [ ] Specification project team contacts the EMO to initiate the review by sending an email to [email protected]. An issue will be created by the EMO to track the release review. Reference the https://projects.eclipse.org/projects/ee4j.jaxb/releases/3.0 release page. | ||
|
There was a problem hiding this comment. Can the reference be MicroProfile project - https://projects.eclipse.org/projects/technology.microprofile or do we need to wait for finished release first? There was a problem hiding this comment. It needs to reference a release under the https://projects.eclipse.org/projects/technology.microprofile. I don't see any currently under there, so one needs to be created. Only the platform spec would need to contact the EMO on behalf of all other specs. There was a problem hiding this comment. The releases have since been created and/or updated. We can use one of these as the example. There was a problem hiding this comment. We forgot to include the final step, the Result Ballot notification after the initiated ballot is sent. |
||
| - [ ] The specification project team requests approval for the release from the PMC by sending an email to [email protected]. | ||
| - [ ] The specification project team then delivers an IP Log to the IP Team for their review as described in https://www.eclipse.org/projects/handbook/#pmi-commands-iplog. This is done by accessing the https://projects.eclipse.org/projects/ee4j.jaxb/releases/3.0 page, logging in, and using the committer tools menu on the left. | ||
|
|
||
| 11. Update Microprofile Parent BOM | ||
| - [ ] Update the Microprofile BOM by submitting a PR to the https://github.com/eclipse/microprofile-bom that updates the version number of your API jar file. | ||
|
|
||
| 12. Specification ballot complete | ||
| - [ ] The specification committee has complete the review ballot successfully | ||
|
|
||
| 13. EMO approval | ||
| - [ ] The EMO has approved the release tracking issue: https://bugs.eclipse.org/bugs/show_bug.cgi?id=565959 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it is best to point to the release artifact, such as https://download.eclipse.org/microprofile/microprofile-config-2.0-RC1/microprofile-config-spec.html
In this case, there is no need to upload the artifacts somewhere else and less error prone.
Therefore, I suggest the form -release-version.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The https://download.eclipse.org/microprofile/ directory is too flat in my opinion. The content should be structured based on the current platform version with the specifications under that. So there should be a
https://download.eclipse.org/microprofile/4.0 directory that contains the microprofile-config-2.0-RC1 contents for example.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See the https://groups.google.com/u/1/g/microprofile/c/azQZccjYTPE discussion
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have simplified the format, review again please
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we are talking about individual spec releases. I think for the time being, the file structure for the spec pdf, html and javadoc can be under these kind of format: https://download.eclipse.org/microprofile/- e.g. https://download.eclipse.org/microprofile/microprofile-config-2.0-RC3/microprofile-config-spec.pdf