search

microprofile / microprofile-wg

Repo to host official Working Group documents under revision control
Apache License 2.0
12 stars 12 forks source link

MP Config 2.0 spec release Dry Run #4

Closed Emily-Jiang closed 3 years ago

Emily-Jiang commented 3 years ago

- [ ] [Release Review](https://www.eclipse.org/projects/handbook/#release-review) - [x] Follow [governance process](https://projects.eclipse.org/projects/technology.microprofile/governance) and create/update release record - [Component Release Record](https://projects.eclipse.org/projects/technology.microprofile/releases/config-2.0) - [ ] [Email to PMC](mailto:technology-pmc@eclipse.org) - [ ] Start release review by [emailing EMO](mailto:EMO@eclipse-foundation.org) (Track the bug issue created by EMO after the email) - [ ] send microprofile-wg for voting

kwsutter commented 3 years ago

Having the extra "pdf" and "html" in the spec file names should not be a requirement. Maven already allows the same file name with different type extensions. Let's clean that up.

Emily-Jiang commented 3 years ago

In order to push both .pdf and .html under the same dir, we have to use classifier to differentiate. We had a lengthy conversation here

radcortez commented 3 years ago

Hum, actually I had a better look I think that the attach plugin supports it. Let me give it a try.

kwsutter commented 3 years ago

Hum, actually I had a better look I think that the attach plugin supports it. Let me give it a try.

Thanks, @radcortez. This should be doable.

kwsutter commented 3 years ago

For the Compatible Impl and TCK section, should we reference a version of your compatible-certification-request.md template? But, we need to indicate that this is filed against the Specification Component repo (ie. microprofile-config), not the microprofile-wg repo.

kwsutter commented 3 years ago

I made several updates to the top level Comment with the hope that my other comments and suggestions hold... I think this is getting very close to translating to a template.

radcortez commented 3 years ago

https://github.com/eclipse/microprofile-config/pull/652 should remove the classifier names in the spec files. I'm not going to rerelease just yet. We may need additional changes.

radcortez commented 3 years ago

For the Compatible Impl and TCK section, should we reference a version of your compatible-certification-request.md template? But, we need to indicate that this is filed against the Specification Component repo (ie. microprofile-config), not the microprofile-wg repo.

Is this required also for the Release Review? Or only for additional implementations after the compatible implementation submitted for the Release Review? Because some of this information is already included in the spec release information. If required, we can add missing information.

radcortez commented 3 years ago

BTW, what do you think is missing so we can proceed with an actual MP Config 2.0 release?

Emily-Jiang commented 3 years ago

For the Compatible Impl and TCK section, should we reference a version of your compatible-certification-request.md template? But, we need to indicate that this is filed against the Specification Component repo (ie. microprofile-config), not the microprofile-wg repo.

Is this required also for the Release Review? Or only for additional implementations after the compatible implementation submitted for the Release Review? Because some of this information is already included in the spec release information. If required, we can add missing information.

I think in order to release a spec, we need at least one compatible implementation. We will need to craft a web page to store the compatible implementation lists in the individual spec repo after the release.

Emily-Jiang commented 3 years ago

eclipse/microprofile-config#652 should remove the classifier names in the spec files. I'm not going to rerelease just yet. We may need additional changes.

@radcortez can you perform a release so that the links to the pdf/html/javadoc are workable for tomorrow's meeting? We can always do further changes based on the meeting.

Emily-Jiang commented 3 years ago

BTW, what do you think is missing so we can proceed with an actual MP Config 2.0 release?

I think we will run through the list and confirm on tomorrow's call to see whether this is the checklist we should use for all specs and then allow specs to release their final RCx, followed by final release.

Emily-Jiang commented 3 years ago

@kwsutter @radcortez I have tidied up this issue to refer to the latest MP Config 2.0-RC10 and all links are good. We can run through this issue on our Live hangout this week.

radcortez commented 3 years ago

RC-10: https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1358/ Specs: https://oss.sonatype.org/content/repositories/orgeclipsemicroprofile-1358/org/eclipse/microprofile/config/microprofile-config-spec/2.0-RC10/

kwsutter commented 3 years ago

This is looking very good! I found a couple of items that will need to be addressed (but not before our meeting today)...

Thanks for working through these items. I think we're in good shape for the meeting today.

radcortez commented 3 years ago

This is looking very good! I found a couple of items that will need to be addressed (but not before our meeting today)...

  • The javadoc does not have a reference to the EFSL. The normal convention is to have this available in this location: doc-files/speclicense.html.

We can add this.

  • The Eclipse download item says that this isn't used anywhere... But, don't we use this for the github release page? That's what I would recommend.

Sorry, what we meant here is that the link is available, but not published, in the sense that you can only access it if you know the direct link, since it is not reference in anywhere at this point. The GH Release page will only reference it after the approval.

  • For the Release Review section, should we indicate that these steps are only used for the "final" release review. That is, we don't want everyone to be sending in the emails, ip logs, etc for these RC releases.

Yes. This was to dry run as it was a final release, but we didn't complete these steps for the reason you point out :)

Emily-Jiang commented 3 years ago 
    The Eclipse download item says that this isn't used anywhere... But, don't we use this for the github release page? That's what I would recommend.

Sorry, what we meant here is that the link is available, but not published, in the sense that you can only access it if you know the direct link, since it is not reference in anywhere at this point. The GH Release page will only reference it after the approval.

I think we can omit this link as we use staging repo for approval. For now, I deleted "it is not used anywhere" as I think it does not add much value rather confusing.

kwsutter commented 3 years ago

@Emily-Jiang and @radcortez, We need to get the EFSL licenses figured out before we can go forward with this ballot. The Specs need to have the EFSL in the generated docs (both pdf and html) and the Javadoc needs to have a link available in the footer. Here's an example (look at spec pdf, html, and javadoc links): https://deploy-preview-252--jakartaee-specifications.netlify.app/specifications/platform/9/

kwsutter commented 3 years ago

Here are some additional items that we check for with Jakarta EE... I've deleted many of the items from our checklist that are specific to Jakarta EE. These are the remaining items... For reviewing purposes, where should we put this type of checklist?

Still not clear on how thorough we're going to be with the TCK... As far as User Guides, etc. But, we do need the EFTL license, I suppose...

Spec Review Checklist

  1. Spec Issue

  2. javadocs

    • [x] Footer contains Eclipse copyright and link to license
    • [x] ESFL license is included, usually as doc-files/speclicense.html
    • [x] no META-INF directory in PR
    • [x] javadocs-jar artifact matches apidocs (optional for this release)

  3. Spec PDF

    • [x] Correct spec title
    • [x] Version number of the form x.y, not x.y.z (exception for Platform and Web Profile specs)
    • [x] Correct Eclipse copyright line
    • [x] No DRAFT or SNAPSHOT
    • [x] Correct Logo

  4. Spec HTML

    • [x] Same as PDF

  5. TCK zip file

    • [x] README file (optional for this release)
    • [x] EFTL license file, preferably named LICENSE.md
    • [x] User's Guide (or equivalent documentation)
    • [x] How to test the Compatible Implementation(s) listed in _index.md above with the TCK (may be in UG)

  6. TCK User's Guide (or equivalent documentation)

    • [x] Software requirements listed
    • [x] Installation and configuration described
    • [x] How to run tests
    • [x] Where to file challenges

  7. Compatibility certification request

    • [x] Request follows template
    • [x] SHA-256 fingerprint matches staged TCK zip file
    • [x] Request issue has certification label.

  8. TCK results summary

    • [x] Page is hosted by Compatible Implementation project
    • [x] Includes all information from certification request
    • [x] Summary includes number of tests passed, failed, errors
    • [x] SHA-256 fingerprint matches staged TCK zip file on cert request
radcortez commented 3 years ago

@Emily-Jiang and @radcortez, We need to get the EFSL licenses figured out before we can go forward with this ballot. The Specs need to have the EFSL in the generated docs (both pdf and html) and the Javadoc needs to have a link available in the footer. Here's an example (look at spec pdf, html, and javadoc links): https://deploy-preview-252--jakartaee-specifications.netlify.app/specifications/platform/9/

Ok, I'll have a look into this tomorrow.

Still not clear on how thorough we're going to be with the TCK... As far as User Guides, etc. But, we do need the EFTL license, I suppose...

Usually the TCK module as a README or some other documentation file with the instructions. For instance: https://github.com/eclipse/microprofile-config/blob/92e5af2e7c0c4bc9c066470a16ee9002c3cd46ca/tck/running_the_tck.asciidoc. Is this enough? Should this be generated in some sort of pdf / html and added to the TCK dist binary?

Emily-Jiang commented 3 years ago

@Emily-Jiang and @radcortez, We need to get the EFSL licenses figured out before we can go forward with this ballot. The Specs need to have the EFSL in the generated docs (both pdf and html) and the Javadoc needs to have a link available in the footer. Here's an example (look at spec pdf, html, and javadoc links): https://deploy-preview-252--jakartaee-specifications.netlify.app/specifications/platform/9/

Ok, I'll have a look into this tomorrow.

The Config pdf and html has the following copyright already in the body

Specification: Configuration for MicroProfileVersion: 2.0-RC9Status: DraftRelease: November 04, 2020Copyright (c) 2016-2018 Contributors to the Eclipse FoundationLicensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License. See here for pdf page 1 and html

The javadoc has the EFSL on the footer. See here

Copyright © 2020 Eclipse Foundation. All rights reserved.

Still not clear on how thorough we're going to be with the TCK... As far as User Guides, etc. But, we do need the EFTL license, I suppose...

Usually the TCK module as a README or some other documentation file with the instructions. For instance: https://github.com/eclipse/microprofile-config/blob/92e5af2e7c0c4bc9c066470a16ee9002c3cd46ca/tck/running_the_tck.asciidoc. Is this enough? Should this be generated in some sort of pdf / html and added to the TCK dist binary?

We should be fine with the user guide. We do have Apache Lience v2 and EF copyright on both the jar level and source file level. @kwsutter I think MP Config 2.0 can go for a final release. Thoughts?

radcortez commented 3 years ago

The Config pdf and html has the following copyright already in the body

What we have is the Apache License. This raises another question. Do we need to change the license and move to EF based licenses?

The javadoc has the EFSL on the footer. See here

Copyright © 2020 Eclipse Foundation. All rights reserved.

This is just the copyright. There is no link for any license, either EF or Apache.

I think MP Config 2.0 can go for a final release. Thoughts?

I think we need to clear this License question. @kwsutter can you help?

Emily-Jiang commented 3 years ago

@radcortez btw, we don't need to change the license from Apache v2 to EF, which was set when MicroProfile moved to EF. As for the javadoc, as I mentioned in the previous notes, the license used is also Apache V2, which are listed in the source files. I think one question is whether we can add a link to the footer. @kwsutter?

kwsutter commented 3 years ago

@radcortez and @Emily-Jiang The license for the specification source is Apache v2. That's fine and should be left that way. But, the generated Specification has to be EFSL licensed. The Apache v2 license is not sufficient for the generated Specification (pdf and html). So, this has to be updated before we are ready.

Similar comment for the Javadoc. The Java source code is Apache v2 licensed. But, the generated Javadoc has to be EFSL licensed. This is easily done by updating the footer for the javadoc. Here's an example of how we do this for Jakarta EE specs: https://github.com/eclipse-ee4j/jakartaee-api/blob/211785b901de26bd3b708112fd0055ca70dadc86/pom.xml#L268

As far as the TCK user's guide... As long as the TCK zip file contains the user's guide in whatever format (html, pdf, asciidoc, whatever), that is sufficient. There are requirements for this user's guide to contain information for setup, configuration, passing criteria, challenges, etc.

Hope this helps!

radcortez commented 3 years ago

@kwsutter Thanks. One more thing: Should the spec keep the ASF license or the EFSL will replace it? I mean, can we keep as is and just add the EFSL?

aeiras commented 3 years ago

It ought to keep both Licences. 🥋

kwsutter commented 3 years ago

It ought to keep both Licences. 🥋

Actually, that is not the case. The source keeps the Apache v2 or EPL or whatever license is used for developing the spec. But, the generated Spec should only only contain the EFSL. As an example, most all of the Jakarta EE specs source are EPL. But, the EPL is replaced with the EFSL when generating the PDF or HTML versions of the final specs and javadoc.

Emily-Jiang commented 3 years ago

Thank you @kwsutter for the clarification! I took a look at the Jakarta spec ascii doc for JMS and got an idea to how to proceed. We need to update the spec docs to add the EFSL. Let me open an issue in MP Config to fix the javadoc and generated specs.

aeiras commented 3 years ago

Kevin,

Please copy/paste your explanation. It is actually correct about the PDF. Only EF is authorized to distribute the code when generating the spec. really easy to miss that formality. thank you!

aeiras commented 3 years ago

I mean, document it within the process. :)

kwsutter commented 3 years ago

I mean, document it within the process. :)

@aeiras, I was talking to @Emily-Jiang about this yesterday... We need an "operations guide" for the MicroProfile specification process. We have one for Jakarta EE, but our MP operations will be slightly different and, thus, we should have a separate "ops guide". Would you like to start one? I just don't have the cycles to do that at this time. Thanks!

aeiras commented 3 years ago

@kwsutter Kevin,

I am happy to own the task if Emily cannot own it but only after I am done completing the final drafts for the MPWG:

aeiras commented 3 years ago

I know about cycles... :) fun yet we must conserve key-strokes to not overcommit & be "flickers".

As usual, I love the candidness of our exchanges Kevin! :) cheers

Emily-Jiang commented 3 years ago

@kwsutter MP Config 2.0-RC15 should have addressed all of the comments in this issue. Can you take a further look at the issue description, which I have updated accordingly to see whether more updates are needed?

kwsutter commented 3 years ago

Let's close this Issue out to avoid confusion with the "real" Config 2.0 Spec Release issue.

radcortez commented 3 years ago

I don't have permissions to do it.

This is something else we need to discuss. Because this repo is on another GH org, MP member, don't have the same permissions / visibilities they have on the EF repos.

Emily-Jiang commented 3 years ago

closed.