Approve and Publish OSLC QM v2.1 PS01

berezovskyi commented 4 years ago

Requester name: Andrew Berezovskyi

OP name: OSLC OP

OP mailing address: oslc-op@lists.oasis-open-projects.org

Title: OSLC Quality Management Version 2.1 Project Specification 01

Approval link: https://lists.oasis-open-projects.org/g/oslc-op/message/316

Notes: The publication date in the generated materials is set to 2020-08-27.

berezovskyi commented 4 years ago

@OASIS-OP-Admin @chet-ensign a reminder for you to open a ballot 7 calendar days from now so that we do not have to edit dates in the specs and machine-readable files, please.

OASIS-OP-Admin commented 4 years ago

Schedule is on my calendar. Set up SMV on 8/19; ballot opens 8/20 - closes 8/27. Publication will follow approval of the ballot.

berezovskyi commented 4 years ago

Thank you

-- Cheers, Andrew

From: OASIS-OP-Admin notifications@github.com Sent: Thursday, August 13, 2020 5:31:53 PM To: oasis-open-projects/administration administration@noreply.github.com Cc: Andrew Berezovskyi andrew@berezovskyi.me; Author author@noreply.github.com Subject: Re: [oasis-open-projects/administration] Publish OSLC QM v2.1 PS01 (#11)

Schedule is on my calendar. Set up SMV on 8/19; ballot opens 8/20 - closes 8/27. Publication will follow approval of the ballot.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHubhttps://github.com/oasis-open-projects/administration/issues/11#issuecomment-673547522, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AAAPZXS272FZRJP7QRN5JBTSAQBOTANCNFSM4PWW3EQA.

OASIS-OP-Admin commented 4 years ago

The Special Majority Vote has been set up at https://lists.oasis-open-projects.org/g/oslc-op-pgb/topic/vote_on_quality_management/76291804?p=,,,20,0,0,0::recentpostdate%2Fsticky,,,20,2,0,76291804.

The ballot will close on Aug. 27th at which point we will announce our first approved Project Specification and publish it to docs.oasis-open-projects.org.

berezovskyi commented 4 years ago

@OASIS-OP-Admin I believe the vote can be closed as 100% of the PGB members voted YES and 7 days have passed.

berezovskyi commented 4 years ago

We are having an OP call right now. Just checking in with a reminder to close the vote to check an agenda item off.

chet-ensign commented 4 years ago

The ballot to approve QM v2.1 as a Project Specification has closed and passed. All 4 eligible voters cast their votes and all voted in favor of approval. See https://lists.oasis-open-projects.org/g/oslc-op-pgb/topic/vote_on_quality_management/76291804?p=,,,20,0,0,0::recentpostdate%2Fsticky,,,20,2,0,76291804

OASIS staff will now publish the PS and announce it.

Let us know if you have any questions.

berezovskyi commented 4 years ago

Thank you, Chet!

berezovskyi commented 4 years ago

@OASIS-OP-Admin what's the progress on the publication?

paul-knight commented 4 years ago

reviewing - with ps01, there is an additional part added since psd02. looks fine so far...

paul-knight commented 4 years ago

Noted - image file oslc_qm_resources.png appears in two of the three parts - Constraints [shapes] and Vocabulary. The HTML code will apparently not need to be modified to constrain the width when generating the PDF format.

Change which should be applied to the OP's HTML code for Part 2 and Part 3: The date on Part 1: Specification is 27 August 2020, but the date on the other two parts is 14 August. I'm pretty sure all the parts should be 27 August 2020. This only appears twice in each part (subtitle and "Citation format") so I can make this change easily. In the HTML code, there are also a couple of other (non-printing) tags associated with the date. I modified them too.

I verified that the two turtle (.ttl) files have correct dates internally (27 August).

PDF generation looks good - but same as for previous (psd02) publication, I have to let the PDF generation software produce a very small font size in one of the Parts, to avoid truncating tables. Part 1 and Part 2 have very readable fonts, but Part 3 (Constraints (shapes) has smaller, but still readable fonts.

All the files (HTML, PDF, and turtle files) appear ready for staging. I expect to do that fairly early tomorrow, for initial review by TC Admin team.

paul-knight commented 4 years ago

qm-v2.1-staging01.zip Attaching ZIP with files to be used in initial staging review.

paul-knight commented 4 years ago

prepared files with timestamps, ZIP, and manifest in personal directory
verified sync between canonical directory and OASIS-OP Library
synced canonical TC directory to ztest to create staging directory
created stage directory
copied files into stage directory
updated existing symlinks or added new symlinks
installed README warning file
set timestamps for directory and symlinks, also for version directory.
checked installation -- noted issue with PDF handling of the relative links in "Additional components" - they have been turned into fully-qualified links pointing to the local directory where the PDF files were generated. This is probably a limitation of the PDF generation software.

I'll work on a fix (probably using temporary HTML files with fully-qualified links while generating the PDF files.)

paul-knight commented 4 years ago

First test - partial success:

used \ tag in the HTML, and also used a fully-qualified (FQ) link to the image in psd02, which is identical to the current image
tag is \
result: -- PDF has good FQ links for the "Additional components" -- PDF TOC links ALSO point to https://docs.oasis-open-projects.org/oslc-op/qm/v2.1/ps01/quality-management-shapes.html -- not correct

paul-knight commented 4 years ago

Note for Editors: In the main specification (Part 1), Section 3 begins "OSLC QM Resources 2.1 [...]", but it is linked to, and appears to discuss, the Part 2: Vocabulary. The text appears to be misleading. It should refer to part 2: Vocabulary.

(More extensive request below) Also, if possible, it would be good to have this link to the "Additional components" section (which currently has no "id" tag as a target) instead of directly to the Part 2 document via a relative link. "Additional components" will point the reader to the link to Part 2, and should be set up as a fully-qualified link instead of a relative link. Finally, there are two other instances (in Part 1) of relative links to Part 2, both used along with the "QM-2" conformance element (where it first appears in Section 2.1, and where it is listed in Section 5). It would be good to also link these to the "Additional components" section. The issue is that we are currently unable to automatically generate the PDF format containing relative links, when starting with the HTML format. (We would be very happy to hear of a tool to do this.) (For PS01, we have manually inserted fully-qualified links into a temporary HTML file to generate PDF with functioning links.) If the Editors can set up an "id" tag for the "Additional components" section, and also use complete URIs in that section, then any reference to another Part can simply point to that section. This accomplishes the goal of producing a fully functional PDF format, while imposing no significant burden on users of the HTML format. (While something similar could be accomplished by using fully-qualified links instead of pointing to "Additional components", this imposes an additional burden of updating those links for future publication stages.) An alternative to referencing the "Additional components" would be to insert specific references to the other Parts into the References section, and then citing them.

outside of the "Additional components" section, I did not detect relative links in any Part other than Part 1, with the three instances noted above.

paul-knight commented 4 years ago

Second test - looks right so far:

replaced all instances of relative hyperlinks with fully-qualified hyperlinks (did not adjust visible text) within temporary instances of the three HTML files. -- five links in "Additional components" - in each HTML file -- three additional links in Part 1 -- searched for instances of either of the strings: --- \<a href="./quality --- \<a href="quality
generated PDFs
will start staging review

paul-knight commented 4 years ago

Interesting - tested another way to generate "good" PDF, which would be to temporarily install the HTML format in its expected position (along with image files), then use wkhtmltopdf to generate the PDF locally. (Afterwards, remove the installed HTML files and install the entire package in the normal fashion.) I just tested against the existing PSD02... looks good, resulting in PDF files which correct the hyperlink errors that ended up in the installed PDF files there. This would be cumbersome, but less so than editing the hyperlinks, etc. It would still be preferable to avoid the relative links, I think...

paul-knight commented 4 years ago

rebuilt installation package with corrected PDF files (based on inserting fully-qualified hyperlinks into temporary HTML files)
re-installed into staging server; reset timestamps, etc.
requested staging review:

Please review the staging server installation of the files for OSLC Quality Management v2.1 ps01.

I recognized a serious shortcoming of the HTML-to-PDF tool we are using (wkhtmltopdf) - it does not handle relative links as expected, and just turns them into links based on the URI of the source HTML. (For a good example, take a close look at the hyperlinks under "Additional components" in the previous stage, https://docs.oasis-open-projects.org/oslc-op/qm/v2.1/psd02/quality-management-spec.pdf.)

I tried a couple of approaches to avoid this. The PDF files under review (below) have been generated from HTML which was manually edited to replace the relative links with fully-qualified links. I did not include the edited HTML for review.

I'm not so happy with the small font for the Part 3 "shapes" PDF, but it's unavoidable with the large tables in that document.

The files are:

OSLC Quality Management Version 2.1 Project Specification 01 27 August 2020

Please add comments to https://github.com/oasis-open-projects/administration/issues/11. (or https://issues.oasis-open.org/browse/TCADMIN-3790).

Attaching new staged files (ZIP) qm-v2.1-staging02.zip

paul-knight commented 4 years ago

Note - Monday September 7 is a US holiday.

paul-knight commented 4 years ago

Summary of editorial changes recommended for future publications:

on front page in "Additional components", use fully-qualified links (similar to "This stage" URIs) to all the components. Both the visible links and hyperlinks should be FQ.
add a named link to the "Additional components" section, and set up any document cross-references to any of the components with links to this named link.
an alternative to referencing the "Additional components" would be to insert specific references to the other Parts into the References section, and then citing them.

paul-knight commented 4 years ago

One more editorial request for future publications - probably applies to all OSLC-OP publications:

In the Status section, the link provided after "Any other numbered Versions and other technical work produced by the Open Project are listed at [...]" should point to https://open-services.net/specifications/ for additional versions of the specifications, not to https://open-services.net/about, which just lists the PGB and TSC members.

paul-knight commented 4 years ago

Just realized that the "Previous stage" links are not provided - all are still set to "N/A". This needs to be modified for Part 1 and Part 2, but not for Part 3, which is a new addition.

I'll fix this, and get the files ready for final review (sanity check).

paul-knight commented 4 years ago

Added the "Previous stage" links to Part 1 and Part 2. Changed the target for the phrase "Any other numbered Versions and other technical work produced by the Open Project are listed at [...]" to be https://open-services.net/specifications/ (since other changes were needed).

Installed updated files into canonical directory (/htdocs)
Synced to OP Library (docs.oasis-open-projects.org)
checked links, etc. -- no link issues noted
requested sanity check:

Please review the OASIS-OP Library installation of the files for OSLC Quality Management v2.1 ps01.

Since I had to insert the "Previous stage" links, I also added the recommended change to the link in "Status" (to /specifications instead of /about).

I did want to raise a question about the use of "Part 4" and "Part 5" for the machine-readable turtle files. I think this usage of "Part" (to identify individual machine-readable files) should be discouraged. It seems to contradict the intent of the Naming Directives, which only discuss "separately-titled prose parts" [1], and would quickly become unwieldy as the number of machine-readable files increases. (Also note that the turtle files themselves do not contain the titles which are listed for them on the front pages - "OSLC Quality Management Version 2.1. Part 4: Machine Readable Vocabulary Terms", etc.)
(For future publications by OSLC - no need to change here now.)

Final note - I just realized that I have not prepared DIFF files yet. I'll go ahead and create them, and do a quick replacement. Review can take place with or without them...

The files are:

OSLC Quality Management Version 2.1 Project Specification 01 27 August 2020

Please add comments to https://github.com/oasis-open-projects/administration/issues/11. (or https://issues.oasis-open.org/browse/TCADMIN-3790)

[1] http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#URIs-MP

chet-ensign commented 4 years ago

I reviewed the files. They look like they are good to go. I approve to release.

paul-knight commented 4 years ago

Since there are extensive structural changes (three main parts instead of two), I think a set of DIFF files will not be very helpful. In addition, the github repository can provide a detailed history of each change. I'll skip the DIFF files here, and go ahead and release and announce the files.

OASIS-OP-Admin commented 4 years ago

That works for me.

paul-knight commented 4 years ago

Note for Editors: Although it is a good idea to provide references to the "machine-readable" files like the turtle files, please DON'T use labels like "Part 4" and "Part 5" for them (in the "Additional components" section). The files themselves do not have those titles anywhere.

So, instead of "OSLC Quality Management Version 2.1. Part 4: Machine Readable Vocabulary Terms.", please just use a reference like "Machine Readable Vocabulary Terms." or "Machine Readable Constraints". Also, as noted in an earlier comment, it would be better to use the fully-qualified path instead of relative links for all of the components listed within the "Additional components" list.

berezovskyi commented 4 years ago

@chet-ensign @paul-knight thank you!

@paul-knight can we use Appendix A and Appendix B in place of Part 4 and Part 5 respectively? And we will use FQDNs from now on, thank you.

paul-knight commented 4 years ago

@berezovskyi The usual reference would be something like what is used in https://docs.oasis-open.org/kmip/kmip-profiles/v2.1/cs01/kmip-profiles-v2.1-cs01.html - see "Additional artifacts". (extracted below)

This prose specification is one component of a Work Product that also includes: · Mandatory test cases: https://docs.oasis-open.org/kmip/kmip-profiles/v2.1/cs01/test-cases/kmip-v2.1/mandatory/. · Optional test cases: https://docs.oasis-open.org/kmip/kmip-profiles/v2.1/cs01/test-cases/kmip-v2.1/optional/.

That example does not have multiple parts, so only the machine-readable files are listed.

Instead of calling them something like a "Part" or "Appendix", I would recommend using something like:

QM Vocabulary definitions file: https://docs.oasis-open-projects.org/oslc-op/qm/v2.1/ps01/quality-management-vocab.ttl
QM Resource Shape Constraints definitions file: https://docs.oasis-open-projects.org/oslc-op/qm/v2.1/ps01/quality-management-shapes.ttl

(maybe there a a better term than "definitions file"...?)

I based the titles on the internal documentation:

dcterms:title "OSLC Quality Management (QM) Vocabulary" ;
dcterms:title "OSLC Quality Management (QM) Resource Shape Constraints" ;

berezovskyi commented 4 years ago

Thank you Paul, we will do that.

OASIS-OP-Admin commented 4 years ago

The Project Specification is now published. Paul announced to the OP mailing list. I announced on the OASIS homepage (https://www.oasis-open.org/news/announcements/oslc-quality-management-version-2-1-from-the-oslc-open-project-is-approved-as-our), LinkedIn, Twitter, Facebook and also emailed the announcement to the members@ mailing list and the oslc-op@ mailing list.

I also added it to the OASIS Standards page at https://www.oasis-open.org/standards#oslc-qm-2.1.

There are no other tasks to complete so I'm closing the ticket.

oasis-open-projects / administration

Approve and Publish OSLC QM v2.1 PS01 #11