Publish OSLC AM v3.0 PSD01

berezovskyi commented 4 years ago

Requester name: Andrew Berezovskyi

OP name: OSLC OP

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

Title: OSLC Architecture Management v3.0 PSD 01

Request link: https://lists.oasis-open-projects.org/g/oslc-op/topic/intent_to_publish_oslc_am_psd/76437041?p=,,,50,0,0,0::recentpostdate%2Fsticky,,,50,2,0,76437041

Notes: @berezovskyi will initiate a PGB vote on September 10. Please check the package for OASIS rule conformance in parallel to enable publication with minimal delays.

chet-ensign commented 4 years ago

Acknowledged. We'll watch for the results of the PGB vote on Sept. 10.

berezovskyi commented 4 years ago

@OASIS-OP-Admin is it possible to do pre-publication review for the package in parallel, please? We have not received any critical feedback so far.

berezovskyi commented 4 years ago

@OASIS-OP-Admin we just held a PGB meeting. 3/4 members were in attendance. 3/3 attending members voted to promote AM PSD: https://lists.oasis-open-projects.org/g/oslc-op-pgb/topic/pgb_minutes/76756760?p=,,,50,0,0,0::recentpostdate%2Fsticky,,,50,2,0,76756760

Please proceed with the package review and publication.

berezovskyi commented 4 years ago

@paul-knight did you have a chance to check the package? Thank you in advance!

paul-knight commented 4 years ago

It would be very helpful to provide a link for the ZIP file in this ticket:

https://github.com/oslc-op/oslc-specs/releases/download/untagged-0d57e448f2a979d2add1/am-v3.0-psd01.zip
although I'll see if I can remember the generic link for the releases: https://github.com/oslc-op/oslc-specs/releases/

Hmmm. seeing some problems:

Part 1 - spec:

"Additional components" only shows two of the five parts (all five are listed in Part 2) (but be aware of change needed - see Part 2/3 - Constraints)
Under "Latest stage", the hyperlink under "https://docs.oasis-open-projects.org/oslc-op/am/v3.0/architecture-management-spec.pdf" points to the HTML instead of the PDF (This is broken in all three parts!)
Under Normative references, the URL for [OSLCCore3] should be the OASIS link, since it is published: Latest stage: https://docs.oasis-open-projects.org/oslc-op/core/v3.0/oslc-core.html (similar to treatment of [OSLCPreview] ) (this is used in all three main parts - would be good to change all)
In Appendix A, the link appears to be broken.

Part 2 - Constraints (This should be "Part 3", I think) (also change in the Citation format)

All of the URIs use "shape", but the file is named "shapes", and is listed in "Additional components" as "shapes"
Also in "Additional components", this is listed as Part 3, but the title says Part 2. I think "3" is correct.

Real Part 2 - Vocabulary

Section 2 - Example 1 - it is preferred to use "example.com" instead of "acme.com", since acme.com is a real site.

jamsden commented 4 years ago

Part 1 - spec:

[x] "Additional components" only shows two of the five parts (all five are listed in Part 2) (but be aware of change needed - see Part 2/3 - Constraints)
[x] Under "Latest stage", the hyperlink under "https://docs.oasis-open-projects.org/oslc-op/am/v3.0/architecture-management-spec.pdf" points to the HTML instead of the PDF (This is broken in all three parts!) - see ReSpec issue: https://github.com/oasis-tcs/tab-respec/issues/42
[x] Under Normative references, the URL for [OSLCCore3] should be the OASIS link, since it is published: Latest stage: https://docs.oasis-open-projects.org/oslc-op/core/v3.0/oslc-core.html (similar to treatment of [OSLCPreview] ) (this is used in all three main parts - would be good to change all)
[x] In Appendix A, the link appears to be broken.

Part 3 - Constraints

[x] This should be "Part 3", I think (also change in the Citation format)
[x] All of the URIs use "shape", but the file is named "shapes", and is listed in "Additional components" as "shapes" - Yes, to indicated the file is a collection of individual shapes.
[x] Also in "Additional components", this is listed as Part 3, but the title says Part 2. I think "3" is correct.

Real Part 2 - Vocabulary

[x] Section 2 - Example 1 - it is preferred to use "example.com" instead of "acme.com", since acme.com is a real site.

paul-knight commented 4 years ago

I'm assuming that there will be a note placed here when the updated files are ready. If the only remaining issue is the "Latest stage" hyperlink, I will be happy to fix that manually...

jamsden commented 4 years ago

I plan on giving you a new zip file soon.

jamsden commented 3 years ago

The updated Zip file is here: https://github.com/oslc-op/oslc-specs/releases/download/untagged-ed7751fd51dac5e2a28d/am-v3.0-psd01.zip

paul-knight commented 3 years ago

Thanks, Jim! I'm pretty sure I can get this out next week. Should be by 22 October.

paul-knight commented 3 years ago

Reviewed files briefly - no issues noted. Prepared PDF files by temporarily loading the HTML files into the OASIS OP Library and using them as the sources for WKHTMLTOPDF. Set up installation scripts and support files. Should be ready for staging operations.

paul-knight commented 3 years ago

Installed files in staging directory:

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 new Work Product, Version, and stage directory - am/v3.0/psd01
copied files into stage directory
added 6 new symlinks
installed README warning file
set timestamps for directory and symlinks, also for version directory.
checked installation -- Looks good - noted typo in Part 3 Constraints - Section 2.1, in the table, the "Description" for "jazz_am:refine" begins with "TThe" instead of "The"
requested OASIS staff staging review:

Please review the staging server installation of the files for OSLC AM-v3.0-psd01.

This has three main parts, with two Turtle files. The files are:

OSLC Architecture Management Version 3.0 Project Specification Draft 01 17 September 2020

Please add comments to https://github.com/oasis-open-projects/administration/issues/15. Also tracked in https://issues.oasis-open.org/browse/TCADMIN-3799.

Attaching ZIP file for review by OP members, if desired: am-v3.0-psd01.zip

OASIS-OP-Admin commented 3 years ago

All looks good to me. I approve to promote to docs.oasis-open-projects.org

paul-knight commented 3 years ago

Synced files from /ztest to canonical directory (/htdocs)
Synced to OP Library (docs.oasis-open-projects.org)
checked links, etc. -- Part 1 - Three links to open-services.net are currently "404" - broken. Presumably the OSLC team which controls that domain will install the targets. -- Same for Part 2 (vocab) -- Part 3 failed - needs to be rebuilt - used wrong self-referential URIs on its front page (This stage and Latest stage at top, plus both URIs in the "Citation format" block). Part 3 uses "shape" instead of "shapes" in its URIs. - But its own file name and every cross-reference to it uses "shapes". I also listed this error as part of my comments on Sept. 17 above. -- To be clear, the six self-referential URIs listed on the front page MUST point to the file itself. The file is named "architecture-management-SHAPES.html", but the URIs listed on the front page all use "architecture-management-SHAPE.html", without the "S". I will go ahead and fix this, but the OSLC OP Editor needs to make this change in their source as well.
Cannot release yet. Should be ready Monday (10/26)
I'll leave the files in place over the weekend for internal review if desired, with the "AA-README-Warning-Do-Not-Download.txt" file in place.

paul-knight commented 3 years ago

Patched up the HTML file for Part 3 (replaced all "shape" with "shapes" in all URIs). Installed it temporarily into OASIS OP Library and generated PDF for Part 3. Updated the base-tagged HTML file for Part 3. Removed all the files in https://docs.oasis-open-projects.org/oslc-op/am/v3.0/psd01/. Should be ready for rebuilding the installation package and re-installing.

paul-knight commented 3 years ago

NOTE ON PDF GENERATION:

We generate the PDF from the HTML source using WKHTMLTOPDF. WKHTMLTOPDF does not preserve "relative links" - they are all transformed into fully-qualified domain name (FQDN) links. This means that the HTML file must be located in its intended location (in the OASIS OP Library - https://docs.oasis-open-projects.org/) before the PDF can be generated. We temporarily install the HTML file, then generate the PDF, then remove the HTML. Then we can construct the installation package (which contains a ZIP file with all components, and a manifest file with cryptographic hashes of each file).

There is another way to generate the PDF, by replacing every relative link in a temporary copy of the HTML file with a FQDN link, but it is more error-prone.

paul-knight commented 3 years ago

Files reinstalled. The only items I noted are the broken links for the open-services.net controlled URIs used for "Latest version" and "Latest editor's draft", plus the namespace links in "RDF Namespaces". Parts 1 and 2 have one namespace, while Part 3 has two. Requested sanity check before release:

Please review the OASIS OP Library installation of the files for OSLC AM-v3.0-psd01.

I did not note any issues other than the broken links for the open-services.net controlled URIs used for "Latest version" and "Latest editor's draft", plus the namespace links in "RDF Namespaces". I'll let the OP know about those, as well as the need to correct their copy of Part 3 (with its bad self-referential URIs which I corrected here).

The files are:

OSLC Architecture Management Version 3.0 Project Specification Draft 01 17 September 2020

Please add comments to https://github.com/oasis-open-projects/administration/issues/15. Also tracked in https://issues.oasis-open.org/browse/TCADMIN-3799.

chet-ensign commented 3 years ago

I checked over the files. They look ready to go. I approve to release.

paul-knight commented 3 years ago

Removed README warning file and reset directory timestamp in canonical directory on staging server.
synced to OP Library (docs.oasis-open-projects.org)
Ready for announcements.

paul-knight commented 3 years ago

Sent email announcement to OSLC email list:

https://lists.oasis-open-projects.org/g/oslc-op/message/376

I also sent a note to the Editors to make sure they know about the remaining issues:

update source files for Part 3 to use "SHAPES" instead of SHAPE
set up targets for the open-services.net controlled URIs used for "Latest version" and "Latest editor's draft", plus the namespace links in "RDF Namespaces" (in all Parts).

Should be all done here - ready to close issue.

berezovskyi commented 3 years ago

Thank you, I added your issues to the AM PS01 backlog.

jamsden commented 3 years ago

I have fixed the -shape.html" to -shapes.html" (5).

oasis-open-projects / administration

Publish OSLC AM v3.0 PSD01 #15