Re: ReSpec updates
|
Nick Crossley <nick_crossley@...>
I agree with Andrew.
We cannot use the URIs Jim suggests for the authoritative 'this' version - https://github.com/oslc-op/oslc-specs/blob/cm-v3.0-psd01/specs/cm/change-mgt-spec.html- it does not even render as HTML. Jim wrote: This issue I have with your current approach: specStatus : "PSD", shortName : "oslc-core", conformanceLabelPrefix: "CORE", label: "3.0-psd-04", citationLabel: "OSLC-Core-3.0-Part1", is that the critical OASIS spec identification information: specStatus and revision, are not specifically defined, and used to generate the URLs, citation label, etc. There is also some redundancy in the above in that specStatus is repeated in 3 variables. This could introduce errors. I do not understand all these comments. the specStatus is specifically defined. Revision is not, because I do not see a single revision concept here. I see an OSLC version, and a document revision level within that. In the previous revisions of ReSpec, we did have two different variables for this, but the OSLC version variable ended up not being used. Having a single 'label' string that the authors can format as needed is both simpler and more flexible. You could even put slash characters in it if you wanted to form a path. The specStatus is not repeated three times, it is repeated twice, because I wanted to show that you could encode the status in the label if you wanted to - but that is not required; label is an arbitrary string, one that would be the same as the git tag. Nick. From: Andrii Berezovskyi <andriib@...> To: Jim Amsden <jamsden@...> Cc: Nicholas Crossley <nick_crossley@...>, "chet.ensign@..." <chet.ensign@...>, "oslc-op@..." <oslc-op@...> Date: 07/03/2019 07:28 AM Subject: [EXTERNAL] Re: ReSpec updates Jim, The idea is actually the other way around: that the open-services URLs will appear in the spec and our redirects will point to the locations of OASIS choosing (for the spec editions published there). This will enable us to have a common URL format no matter of the location where specs of different status are published. It will also allow us in the future to update the redirects on the URLs like Latest Editor’s Draft. The reasoning behind relying on open-services.netis that resolution of the RDF documents on the same URIs is even more important than the stability of the spec URIs, so we should be able to ensure reliable operation of those redirects. I previously suggested looking at W3ID (managed by a consortium of some W3C members) or PURL (now managed by the Internet Archive) as a way to specify permanent URLs that can be changed in the future if any links go down. I would actually use such links for all normative references. If OASIS wants, they could run a PURL server under their control. -- /Andrew (from phone) 3 juli 2019 kl. 15:58 skrev Jim Amsden <jamsden@...>: Nick, Thanks for the updates. Although we don't have final agreement with OASIS yet, we're getting close to an agreed spec format, publishing process, and URL naming conventions. There's been a lot of emails going back and forth the last couple of days, and I've tried to keep the tentative agreements updated in https://github.com/oslc-op/oslc-admin/issues/19, using the CM spec as a sample (zip file attached to the issue). Specifically, the URLs would now look like this: This version: https://github.com/oslc-op/oslc-specs/blob/cm-v3.0-psd01/specs/cm/change-mgt-spec.html(Authoritative) https://docs.oasis-open.org/oslc-op/cm/v3.0/psd01/change-mgt-spec.html https://docs.oasis-open.org/oslc-op/cm/v3.0/psd01/change-mgt-spec.pdf Previous version: http://docs.oasis-open.org/oslc-domains/cm/v3.0/cs02/part1-change-mgt/cm-v3.0-cs02-part1-change-mgt.html http://docs.oasis-open.org/oslc-domains/cm/v3.0/cs02/part1-change-mgt/cm-v3.0-cs02-part1-change-mgt.pdf Latest version: https://docs.oasis-open.org/oslc-op/cm/change-mgt-spec.html https://docs.oasis-open.org/oslc-op/cm/change-mgt-spec.pdf We actually like that the authoritative version is the un-rendered source. The open-services.netredirects will be to the This version docs.oasis-open.orgURLs, and will not appear in the OP specification. These are managed by oslc-op TSC, not OASIS. This issue I have with your current approach: specStatus : "PSD", shortName : "oslc-core", conformanceLabelPrefix: "CORE", label: "3.0-psd-04", citationLabel: "OSLC-Core-3.0-Part1", is that the critical OASIS spec identification information: specStatus and revision, are not specifically defined, and used to generate the URLs, citation label, etc. There is also some redundancy in the above in that specStatus is repeated in 3 variables. This could introduce errors. By the way, is there any reason shortName couldn't be just "core"? Do we really need it to be oslc-core? Don't change anything now. Let's wait until we get complete agreement from OASIS on the sample CM spec I sent them. If this gets done before you get back, I might be able to make the necessary ReSpec changes. Otherwise we can wait until you get back, and publish a whole bunch of specs at once. -- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 From: Nicholas Crossley/Seattle/Contr/IBM To: Jim Amsden/Raleigh/IBM@IBMUS Cc: "Andrii Berezovskyi" <andriib@...> Date: 07/02/2019 07:00 PM Subject: Re: ReSpec updates Based on the responses so far, I have updated ReSpec to generate URIs at open-services.net/specifications/short-name-minus-oslc/label/filename.[html|pdf], and a latest version at open-services.net/specifications/short-name-minus-oslc/filename.[html|pdf] (that is, the same with no label). To use this, REMOVE all conf variable definitions for thisVersion, prevVersion, etc., REMOVE the definition of revision and ADD a (now mandatory) conf.label variable with the value you want to appear above. I have checked in a rev of oslc-core.html with these changes so you can see what it looks like. Reminder: the Open Project and updated ReSpec also requires other actions to be taken:
This is rev 2.1.2 of ReSpec. Use version 2.1.1 to get the previous behavior (<script src='https://raw.githack.com/oasis-tcs/tab-respec/master/builds/respec-oasis-common-2.1.1.js'async class='remove'></script>). I'm happy to tweak these as needed later. I'll be around until tomorrow (Wednesday) evening to make emergency fixes. Nick. From: Jim Amsden/Raleigh/IBM To: Nicholas Crossley/Seattle/Contr/IBM@IBMUS Cc: "Andrii Berezovskyi" <andriib@...> Date: 07/02/2019 08:25 AM Subject: Re: ReSpec updates Nick, My reading of https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specificationsis that OASIS specifically requires standards track documents to be published in the OASIS Document Library. This is what we have been doing, and I see no reason to change. We can have redirects at open-services.netto whatever we want, but this is not were published OASIS documents should be managed. OASIS needs full control of the published specs, and open-services.netwouldn't provide this. -- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 From: Nicholas Crossley/Seattle/Contr/IBM To: Jim Amsden/Raleigh/IBM@IBMUS, "Andrii Berezovskyi" <andriib@...> Date: 07/02/2019 10:46 AM Subject: Re: ReSpec updates Jim, Andrew, The only substantive changes to ReSpec that are not yet checked in concern URI generation. Before checking in those changes, I'd like to make sure we're all on the same page as to the likely URIs we want to publish for the specs. Our previous proposal was to use open-services.netURIs as the externally published URI for all stages of all specs, with redirects to whichever hosting service we were using at the time (docs.oasis-open.org, github pages, rawcdn.githack.com/ raw.githack.com, etc.). I've got list in all the flurry of emails and issue updates since the last meeting, but it seems as if Jim is now proposing to have all docs published at docs.oasis-open.orgwhile Andrew is proposing gh-pages. The fact that we still have this variance seems to me to make it even more preferable that we use the open-services.netURIs as primary. Nick. From: Jim Amsden/Raleigh/IBM To: Nicholas Crossley/Seattle/Contr/IBM@IBMUS Date: 07/02/2019 07:29 AM Subject: ReSpec updates Nick, Can you be sure to checkin what you have before you leave for vacation? That way maybe I can make simple cosmetic changes to get things aligned with OASIS PS Template details. Re: generating the edDraftURL, thisVersion, prevVersion, latestVersion URLs. I suggest following the proposal in https://github.com/oslc-op/oslc-admin/issues/19: publishing in https://docs.oasis-open.org, using the OASIS naming conventions for the path, but not the file name. This will provide all the same information, but will not break relative links. Only variation is to trim off oslc- in the [shortName] to reduce redundancy in the pathname, and align with the folder names in the repo, and align with the proposal for tagging published oslc-op documents. OASIS hasn't agreed to this yet, but I'm hoping they will. -- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 |
|
|