|
Re: Submitting the Quality Management Open Project Specification for public review
Very much appreciated, Chet! Have a nice weekend!
--
/Andrew
(from phone)
|
|
|
|
Re: OSLC Specs Search
Very cool! Thanks Andrew!
|
|
|
|
Determine ho to publish Open Project specifications
I have created a
proposal here: https://github.com/oslc-op/oslc-admin/issues/19.
Please provide comments.
-- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 |
|
|
|
Hugo Templates for documentation
Jory Burson
Jim, Alex, Andrew et al, Came across this new set of templates for Hugo Google has in beta and I thought it might be interesting to ya'll: https://github.com/google/docsy - Jory |
|
|
|
Re: Hugo Templates for documentation
Thanks Jory!
toggle quoted message
Show quoted text
Gabriel, what do you think about incorporating this on open services?
Jim, Jad, if it’s not feasible to incorporate on the main site, we can use it for the devguide, which I suggested to migrate to Hugo some time ago.
|
|
|
|
Re: Hugo Templates for documentation
It would be hard
to justify the resource to migrate the current OSLC Developer Guide material
in any way. If we can utilize docsy for new stuff without breaking the
old, then that's fine.
-- Jim Amsden, Senior Technical Staff Member ELM Quality Manager 919-525-6575 From: "Andrii Berezovskyi" <andriib@...> To: "oslc-op@..." <oslc-op@...> Cc: "gabriel.fernandes@..." <gabriel.fernandes@...> Date: 07/01/2019 02:17 PM Subject: [EXTERNAL] Re: [oslc-op] Hugo Templates for documentation Sent by: oslc-op@... Thanks Jory! Gabriel, what do you think about incorporating this on open services? Jim, Jad, if it’s not feasible to incorporate on the main site, we can use it for the devguide, which I suggested to migrate to Hugo some time ago. -- /Andrew (from phone) 1 juli 2019 kl. 20:02 skrev Jory Burson <jory.burson@...>: Jim, Alex, Andrew et al, Came across this new set of templates for Hugo Google has in beta and I thought it might be interesting to ya'll: https://github.com/google/docsy - Jory |
|
|
|
Re: Hugo Templates for documentation
I agree that it should be a good effort but I think Jim was referring to the amount of effort he already spent with Gatsby on https://oslc.github.io/developing-oslc-applications/ 😊
-- –Andrew.
P.S. I think you need to subscribe to the list first but I have changed the setting to allow emails from non-subscribers too, so let’s see how it works!
Från:
Gabriel Fernandes <gabriel.fernandes@...>
Tried sending this to the oslc-op email but got a non-delivery report. Forwarding to you so you also get the answer
From: Gabriel Fernandes
Sent: Monday, July 1, 2019 6:03 PM To: Jim Amsden; oslc-op@... Subject: Re: Re: [oslc-op] Hugo Templates for documentation
I see no problem using docsy.
From: Jim Amsden <jamsden@...>
It would be hard to justify the resource to migrate the current OSLC Developer Guide material in any way. If we can utilize docsy for new stuff without breaking the old, then
that's fine.
|
|
|
|
Re: ReSpec updates
Thanks Nick! I will try your updates on the TRS spec draft.
toggle quoted message
Show quoted text
--
/Andrew
(from phone)
|
|
|
|
Re: ReSpec updates
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 |
|
|
|
Re: ReSpec updates
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.
|
|
|
|
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 |
|
|
|
Re: ReSpec updates
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 |
|
|
|
Re: ReSpec updates
Let’s set up a meeting!
--
/Andrew
(from phone)
|
|
|
|
Re: ReSpec updates
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 |
|
|
|
Re: ReSpec updates
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:
|
|
|
|
Re: Broadcast: oslc-op Weekly Contributors Meeting (Jun 27 10:00 AM GMT in https://meet.jit.si/oslc-op)
Jad El-Khoury
Hi
I will be on holidays until mid-august so will have limited time to attend the telcos. But I hope I can find time to respond to actions via email. regards ______________________________ Jad El-khoury, PhD KTH Royal Institute of Technology School of Industrial Engineering and Management, Mechatronics Division Brinellvägen 83, SE-100 44 Stockholm, Sweden Phone: +46(0)8 790 6877 Mobile: +46(0)70 773 93 45 jad@..., https://www.kth.se/profile/jad -----Original Appointment----- From: Jim Amsden/Raleigh/IBM <jamsden@...> Sent: Monday, 24 June 2019 20:59 To: Jim Amsden/Raleigh/IBM; oslc-op@... Subject: [oslc-op] Broadcast: oslc-op Weekly Contributors Meeting (Jun 27 10:00 AM GMT in https://meet.jit.si/oslc-op) When: Thursday, 27 June 2019 10:00-11:00 America/New_York. Where: https://meet.jit.si/oslc-op oslc-op contributors weekly telecon. OASIS OSLC Open Project group home: https://lists.oasis-open-projects.org/g/oslc-op Dial-in instructions: https://hackmd.io/GBxx8iRLS3Sf-VvZM2z1Dw?both#Dial-in-details oslc-op GitHub Organization: https://github.com/oslc-op Meeting room: https://meet.jit.si/oslc-op ( https://meet.jit.si/oslc-op ) Meeting minutes: https://hackmd.io/@driib/oslc-op-minutes/edit Mailing list: oslc-op@... (archives: https://lists.oasis-open-projects.org/g/oslc-op ) - invite.ics |
|
|
|
OMG API4KB
Hi,
Is this the OMG effort to define APIs? http://www.omgwiki.org/API4KB/doku.phpBecause OSLC is not even in the list of references there. Also, did anyone hear about https://en.wikipedia.org/wiki/ISO_15926? -- –Andrew. |
|
|
|
Re: OMG API4KB
There is an OMG effort to define the SysML v2 API which mentions OSLC. I'm nota familiar with the API4KB working group.
toggle quoted message
Show quoted text
I'm familiar with ISO_15926. It is used a lot in Norway in combination with ontologies. Unfortunately, I only met one ISO_15926 expert from Norway and he wasn't interested in OSLC... -----Original Message-----
From: Andrii Berezovskyi <andriib@...> Sent: Friday, July 05, 2019 12:11 AM To: oslc-op@...; Jim Amsden <jamsden@...>; Axel Reichwein <axel.reichwein@...> Subject: OMG API4KB Hi, Is this the OMG effort to define APIs? http://www.omgwiki.org/API4KB/doku.phpBecause OSLC is not even in the list of references there. Also, did anyone hear about https://en.wikipedia.org/wiki/ISO_15926? -- –Andrew. |
|
|
|
Minutes for 2019-07-18
Hi,
Please find the minutes from today here: https://github.com/oslc-op/oslc-admin/blob/master/minutes/2019/2019-07-18.md
Please add agenda items for the next meeting here: https://hackmd.io/@driib/oslc-op-minutes/edit?both
Cheers, Andrew |
|
|
|
Re: Minutes for 2019-07-18
Nick Crossley <nick_crossley@...>
I have reviewed Andrew's
pull request for ReSpec changes to URI generation, and merged it with my
own changes into master (ReSpec 2.1.4). In doing so, I have restored the
handling of previousMaturity and previousPublishDate - if you set those
conf variables, they will show up in the 'Previous' URIs section of the
header.
Nick. From: "Andrii Berezovskyi" <andriib@...> To: "oslc-op@..." <oslc-op@...> Date: 07/18/2019 08:53 AM Subject: [EXTERNAL] [oslc-op] Minutes for 2019-07-18 Sent by: oslc-op@... Hi,
Please find the minutes from today here: https://github.com/oslc-op/oslc-admin/blob/master/minutes/2019/2019-07-18.md
Please add agenda items for the next meeting here: https://hackmd.io/@driib/oslc-op-minutes/edit?both
Cheers, Andrew |
|
|