[WIP] Begin a specification release review checklist #193
Conversation
Signed-off-by: Scott M Stark <[email protected]>
| - [ ] 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.
MP 4.0: https://projects.eclipse.org/projects/technology.microprofile/releases/microprofile-4.0
Config 2.0 (example): https://projects.eclipse.org/projects/technology.microprofile/releases/config-2.0
There was a problem hiding this comment.
We forgot to include the final step, the Result Ballot notification after the initiated ballot is sent.
can you add the step to Metrics? https://docs.google.com/document/d/1wISp-yRzQZNOHULNekxxg1U18be3v-3CRUswklcpmr8/edit
spec/pull_request_template.md
Outdated
| 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 |
There was a problem hiding this comment.
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.
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.
See the https://groups.google.com/u/1/g/microprofile/c/azQZccjYTPE discussion
There was a problem hiding this comment.
I have simplified the format, review again please
There was a problem hiding this comment.
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
spec/pull_request_template.md
Outdated
| (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 | ||
| _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
spec/pull_request_template.md
Outdated
| <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
spec/pull_request_template.md
Outdated
| - [ ] 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 | ||
| - [ ] 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.
spec/pull_request_template.md
Outdated
| - [ ] 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.
spec/pull_request_template.md
Outdated
| - [ ] Generated IP Log | ||
| - [ ] 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
Signed-off-by: Scott M Stark <[email protected]>
|
Are we ok with this? I would like to have this merged before starting the MP Config Release, to make sure there are no changes in the checklists to use. |
| - [ ] For a [Release Review](https://www.eclipse.org/projects/handbook/#6_3_3_Release_Review): | ||
| - [ ] Updated release record | ||
| - [ ] Generated IP Log (For the microprofile platform release) | ||
| - [ ] Email to PMC |
There was a problem hiding this comment.
Please add PMC's email address by making PMC a hyperlink
There was a problem hiding this comment.
Or, just provide a link to the governance page, which has links for doing all of this (ip log generation and email notificiations).
| - [ ] Updated release record | ||
| - [ ] Generated IP Log (For the microprofile platform release) | ||
| - [ ] Email to PMC | ||
| - [ ] Start release review by emailing EMO |
There was a problem hiding this comment.
Please add EMO's email address by making EMO a hyperlink
@Emily-Jiang Can you clarify your statement? What "close" button are you referring to? In sonatype? MicroProfile committers can request additional permissions by writing an issue against sonatype. A project lead needs to approve the request and then you will have the necessary permissions. If you are referring to something else, please clarify. Thanks. |
|
I guess I'm a little confused on the intent of this PR. Based on our last Hangout call (10/27), I thought we were focused on an Issue Template. But, I still see a PR checklist on this PR, which is still very slanted toward our Jakarta EE process. Is the PR checklist still in play? Or, should that be removed from this PR? I will limit my comments to the Issue Template until I hear otherwise. Thanks! |
| --- | ||
|
|
||
| ## Specification issue template | ||
| When creating a specification project lifecycle review, create issues in the with the content defined as follows. |
There was a problem hiding this comment.
The last part of this sentence needs some work. Were you going to reference the repository with the "in the .." clause? If so, then let's just specify this microprofile repo: https://github.com/eclipse/microprofile. If not, then just remove the "in the.." clause and the sentence still makes sense. Thanks.
| ## Specification issue template | ||
| When creating a specification project lifecycle review, create issues in the with the content defined as follows. | ||
|
|
||
| - [ ] Specification name and version |
There was a problem hiding this comment.
Just to clarify, can we modify this to say "..and the two digit version"? Or, maybe provide an example, such as "MicroProfile Config 2.0"? We have found with Jakarta EE that if we're not specific, then we get different answers that may need to be updated and that frustrates the developers.
| When creating a specification project lifecycle review, create issues in the with the content defined as follows. | ||
|
|
||
| - [ ] Specification name and version | ||
| - [ ] Add a label from one of: creation, plan, progress, release |
There was a problem hiding this comment.
Let's have these labels standout by enclosing in ticky marks: creation, plan, progress, release
Do we need to reference the EFSP (or MPSP) somewhere in this Template so that developers know what these terms mean and why we're requesting what we are requesting?
There was a problem hiding this comment.
I am not sure why we need 4 labels. Besides, this labels are only suitable for spec releases. I think it is better to make it more specific by prefixing SR-Creation etc, so that other github issues won't use these labels. I think we only need three labels: SR-Creation, SR-Progress, SR-Release. When we first create the issue, label it SR-Creation. When making progress, change the label to SR-Progress. When it is ready to be released, change the label to SR-Release
|
|
||
| - [ ] Specification name and version | ||
| - [ ] Add a label from one of: creation, plan, progress, release | ||
| - [ ] A link to a directory under https://download.eclipse.org/microprofile/staging in the form orgeclipsemicroprofile-NNN where |
There was a problem hiding this comment.
This is a little confusing. Are we conflating the sonatype process with our download site within Eclipse? For example, I don't think we currently push our Specification documents out to sonatype/maven. So, to setup a staging repository that contains this type of material seems out of sync.
How is this staging directory populated? And, then how does this staging get promoted to the main download site (https://download.eclipse.org/microprofile)?
| - [ ] A link to a directory under https://download.eclipse.org/microprofile/staging in the form orgeclipsemicroprofile-NNN where | ||
| NNN is the staging repository id assigned to the staged with the following: (Does not apply to creation/plan review lifecycle events.) | ||
| (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.pdf where |
There was a problem hiding this comment.
For Jakarta EE, we decided that the file names should have the version number as well since the files may get separated from the directory structure once they are downloaded. So, -spec-x.y.pdf as an example.
There was a problem hiding this comment.
I checked all of MP specs. There are two types of the formats: spec.pdf and spec-x-y.pdf in a rough split ratio. Kevin made a good point. Let me double check the specs and fix/raise issues to get them fixed.
| _project_ is the microprofile specification short project name (config, health, ...) | ||
| - [ ] Specification HTML in the form of microprofile-_project_-spec.html | ||
| - [ ] An apidocs directory containing the javadoc associated with the API jar. | ||
| - [ ] A copy of the staged api jar, and TCK artifact |
There was a problem hiding this comment.
Copy or a url reference for the staged API? Same question for TCK.
There was a problem hiding this comment.
These staged api jar and tck artifacts are under sonatype. This link will be different. e.g. https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1351/
| - [ ] For a [Release Review](https://www.eclipse.org/projects/handbook/#6_3_3_Release_Review): | ||
| - [ ] Updated release record | ||
| - [ ] Generated IP Log (For the microprofile platform release) | ||
| - [ ] Email to PMC |
There was a problem hiding this comment.
Or, just provide a link to the governance page, which has links for doing all of this (ip log generation and email notificiations).
| - [ ] Generated IP Log (For the microprofile platform release) | ||
| - [ ] Email to PMC | ||
| - [ ] Start release review by emailing EMO | ||
| - [ ] Summary that a Compatible Implementation is complete, passes the TCK, and that the TCK includes sufficient coverage of the specification. |
There was a problem hiding this comment.
Are we going to request a public TCK Results page? Is that the "summary" you are referring to?
| - [ ] Summary that a Compatible Implementation is complete, passes the TCK, and that the TCK includes sufficient coverage of the specification. | ||
| - [ ] For a [Progress Review](https://www.eclipse.org/projects/handbook/#6_3_5_Progress_Review), that sufficient progress has been made on a Compatible Implementation and TCK, to ensure that the spec is implementable and testable. | ||
|
|
||
| Note: If any item does not apply, check it and mark N/A below it. |
There was a problem hiding this comment.
And, add a comment about why it's not applicable...
| @@ -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.
| - [ ] Specification PDF in the form of microprofile-_project_-spec.pdf where | ||
| _project_ is the microprofile specification short project name (config, health, ...) | ||
| - [ ] Specification HTML in the form of microprofile-_project_-spec.html | ||
| - [ ] An apidocs directory containing the javadoc associated with the API jar. |
There was a problem hiding this comment.
I suggest update this to [ ] An apidocs directory containing the javadoc
| - [ ] 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 | ||
| 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.
| - [ ] 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/
| - [ ] Staging repository link of the form | ||
| 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 | ||
| - [ ] 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?
| - [ ] 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.
|
FYI, @starksm64... We're trying to nail down the appropriate template via this Issue created for Config 2.0-RC9... @Emily-Jiang and I were trying to come up with an issue template PR that could be used to make progress (https://github.com/microprofile/microprofile-wg/pulls). We eventually decided it was easier to just create an Issue, work through the proper Description, and then create the Issue Template from the final version. It would be good to get your views and comments on the Issue description. Thanks. (We had a good discussion on this week's MicroProfile hangout call, if you wish to review that for background.) |
test action for an issue milestone workflow
| - [ ] 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.
We forgot to include the final step, the Result Ballot notification after the initiated ballot is sent.
can you add the step to Metrics? https://docs.google.com/document/d/1wISp-yRzQZNOHULNekxxg1U18be3v-3CRUswklcpmr8/edit
This is the start of a set of checklists and specification process docs to follow in MP
Signed-off-by: Scott M Stark [email protected]