Date
1 - 8 of 8
ReSpec updates
|
Thanks Nick! I will try your updates on the TRS spec draft.
toggle quoted message
Show quoted text
--
/Andrew
(from phone)
|
|
|
|
Nick Crossley <nick_crossley@...>
OK - but remember
that I have uncommitted changes to TRS, so try not to make too many parallel
changes there!
Nick. From: Andrii Berezovskyi <andriib@...> To: Nicholas Crossley <nick_crossley@...> Cc: Jim Amsden <jamsden@...>, "oslc-op@..." <oslc-op@...> Date: 07/03/2019 01:14 AM Subject: [EXTERNAL] Re: ReSpec updates Thanks Nick! I will try your updates on the TRS spec draft. -- /Andrew (from phone) 3 juli 2019 kl. 01:01 skrev Nicholas Crossley <nick_crossley@...>: 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 |
|
|
|
Jim,
toggle quoted message
Show quoted text
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.net is 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.
|
|
|
|
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 |
|
|
|
We discussed using
This version: https://github.com/oslc-op/oslc-specs/blob/cm-v3.0-psd01/specs/cm/change-mgt-spec.html(Authoritative) with Chet and he feels it is preferred that the authoritative
version be the actual source and not a rendered version. The published
instances in the OASIS document repository are the rendered versions.
The Project Specifications are for OASIS and under OASIS control as required by https://www.oasis-open.org/policies-guidelines/open-projects-process. open-services.net is the OP home site and is not part of the standardization process. Links to specifications from open-services.net are a convenience to the OSLC community. Version, status and revision are OASIS concepts. PSD, PS, COS must have versions, and can all have revisions reflecting work by the PGB/TSC and feedback from reviews. An OS cannot have revisions, you have to create a new version to make any changes. These are all part of the title of the document, indicating to a reader the state of the specification and therefore how much they can rely on it. Again, I see no reason to change this unless OASIS wants to. Just to be clear, the problems we needed to address are: 1. OP Project Specification format and OASIS boilerplate - we're still waiting on final review of the CM spec from Chet, and the OASIS Project Specification Template 2. Format for published document URLs to avoid breaking relative links between parts of a mult-part specification - the proposal is to apply OASIS naming conventions to the path components, but not the file name. As far as I know, Chet has agreed to this. 3. URL to the immutable, authoritative revision of PDD, PS, COS and OS specifications - Chet has agreed that the tagged GitHub URL to the HTML source is sufficient and should be included in the specification. 4. Where OP specifications are published - this is up to OASIS, either docs.oasis-open.org, or some new site for OPs that OASIS might create. As far as I know, these are the things that are preventing us from actually publishing our OP specs as COS documents. But perhaps issues and emails are perhaps not an effective way to make progress here. I suggest we setup a meeting with Chet, go through the issues and options, come to agreement, get the COS specs published, and focus on query, TRS and configuration management. -- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 From: "Nick Crossley" <nick_crossley@...> To: Andrii Berezovskyi <andriib@...> Cc: "chet.ensign@..." <chet.ensign@...>, Jim Amsden <jamsden@...>, Nicholas Crossley <nick_crossley@...>, "oslc-op@..." <oslc-op@...> Date: 07/03/2019 11:16 AM Subject: [EXTERNAL] Re: [oslc-op] ReSpec updates Sent by: oslc-op@... 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 |
|
|
|
Let’s set up a meeting!
--
/Andrew
(from phone)
|
|
|
|
Nick Crossley <nick_crossley@...>
I agree - but I am
out on vacation from now until Tuesday July 16th.
toggle quoted message
Show quoted text
I cannot see it as desirable for the 'authoritative' link that readers will use to read the current standard appear as the following:  I do not know of other standards (not even links to editor's drafts) that appear like this, and I would not want any standard that I edited to appear like this. Nick. From: "Andrii Berezovskyi" <andriib@...> To: Jim Amsden <jamsden@...>, "oslc-op@..." <oslc-op@...>, "nick_crossley@..." <nick_crossley@...> Cc: "chet.ensign@..." <chet.ensign@...> Date: 07/03/2019 11:19 AM Subject: [EXTERNAL] Re: [oslc-op] ReSpec updates Sent by: oslc-op@... Let’s set up a meeting! -- /Andrew (from phone) On Wed, Jul 3, 2019 at 6:52 PM +0200,
"Jim Amsden" <jamsden@...>
wrote:
We discussed using This version: https://github.com/oslc-op/oslc-specs/blob/cm-v3.0-psd01/specs/cm/change-mgt-spec.html(Authoritative) with Chet and he feels it is preferred that the authoritative version be the actual source and not a rendered version. The published instances in the OASIS document repository are the rendered versions. The Project Specifications are for OASIS and under OASIS control as required by https://www.oasis-open.org/policies-guidelines/open-projects-process. open-services.net is the OP home site and is not part of the standardization process. Links to specifications from open-services.net are a convenience to the OSLC community. Version, status and revision are OASIS concepts. PSD, PS, COS must have versions, and can all have revisions reflecting work by the PGB/TSC and feedback from reviews. An OS cannot have revisions, you have to create a new version to make any changes. These are all part of the title of the document, indicating to a reader the state of the specification and therefore how much they can rely on it. Again, I see no reason to change this unless OASIS wants to. Just to be clear, the problems we needed to address are: 1. OP Project Specification format and OASIS boilerplate - we're still waiting on final review of the CM spec from Chet, and the OASIS Project Specification Template 2. Format for published document URLs to avoid breaking relative links between parts of a mult-part specification - the proposal is to apply OASIS naming conventions to the path components, but not the file name. As far as I know, Chet has agreed to this. 3. URL to the immutable, authoritative revision of PDD, PS, COS and OS specifications - Chet has agreed that the tagged GitHub URL to the HTML source is sufficient and should be included in the specification. 4. Where OP specifications are published - this is up to OASIS, either docs.oasis-open.org, or some new site for OPs that OASIS might create. As far as I know, these are the things that are preventing us from actually publishing our OP specs as COS documents. But perhaps issues and emails are perhaps not an effective way to make progress here. I suggest we setup a meeting with Chet, go through the issues and options, come to agreement, get the COS specs published, and focus on query, TRS and configuration management. -- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 From: "Nick Crossley" <nick_crossley@...> To: Andrii Berezovskyi <andriib@...> Cc: "chet.ensign@..." <chet.ensign@...>, Jim Amsden <jamsden@...>, Nicholas Crossley <nick_crossley@...>, "oslc-op@..." <oslc-op@...> Date: 07/03/2019 11:16 AM Subject: [EXTERNAL] Re: [oslc-op] ReSpec updates Sent by: oslc-op@... 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 |
|
|
|
Hi,
After the call with Chet, Jim, and Nick today I tried my chances with JS by editing ReSpec and tried the results out on the RM spec (sorry Jad :D). Please find attached two rendered specs for the WD and the PSD.
Changes:
Related PRs:
|
|
|