Date   

Re: ReSpec updates

Jim Amsden
 

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:
  • Update all URIs in additional parts (NOT currently auto-generated by ReSpec, but probably will be in the future), biblios, etc.  
  • Replace any explicit references to OASIS TCs and related terms with open project equivalents
  • Remove any IPR Policy sections
  • Remove <hr> between top-level sections, since ReSpec now generates those; keep other wanted <hr> rules.

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

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:
  • Update all URIs in additional parts (NOT currently auto-generated by ReSpec, but probably will be in the future), biblios, etc.  
  • Replace any explicit references to OASIS TCs and related terms with open project equivalents
  • Remove any IPR Policy sections
  • Remove <hr> between top-level sections, since ReSpec now generates those; keep other wanted <hr> rules.

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

Andrii Berezovskyi
 

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.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.

--
/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.net redirects will be to the This version docs.oasis-open.org URLs, 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:
  • Update all URIs in additional parts (NOT currently auto-generated by ReSpec, but probably will be in the future), biblios, etc.  
  • Replace any explicit references to OASIS TCs and related terms with open project equivalents
  • Remove any IPR Policy sections
  • Remove <hr> between top-level sections, since ReSpec now generates those; keep other wanted <hr> rules.

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.net to 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.net wouldn'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.net URIs 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.org while 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.net URIs 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

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:
  • Update all URIs in additional parts (NOT currently auto-generated by ReSpec, but probably will be in the future), biblios, etc.  
  • Replace any explicit references to OASIS TCs and related terms with open project equivalents
  • Remove any IPR Policy sections
  • Remove <hr> between top-level sections, since ReSpec now generates those; keep other wanted <hr> rules.

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

Andrii Berezovskyi
 

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:
  • Update all URIs in additional parts (NOT currently auto-generated by ReSpec, but probably will be in the future), biblios, etc.  
  • Replace any explicit references to OASIS TCs and related terms with open project equivalents
  • Remove any IPR Policy sections
  • Remove <hr> between top-level sections, since ReSpec now generates those; keep other wanted <hr> rules.

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.net to 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.net wouldn'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.net URIs 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.org while 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.net URIs 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: Hugo Templates for documentation

Andrii Berezovskyi
 

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@...>
Datum: måndag, 1 juli 2019, W27 23:08
Till: Andrii Berezovskyi <andriib@...>
Ämne: Fw: Re: [oslc-op] Hugo Templates for documentation

 

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.

It would have to be a separate site (something like docs.open-services.org maybe?) as it's a Hugo theme, and supporting multiple themes in a single site is not natively supported. It could work in our favor to do that as providing access for collaboration could be easier since collaborators would only need access to the documentation repository and not the whole site.

The way I see it, this should be the opportunity to either create new documentation (that replaces the old) or to migrate any still relevant documentation into it. Having a single consolidated source of documentation, in my opinion, is the best user experience we can provide. That leads to easier adoption, easier discussions, easier contributions and so on.

That said we could easily just add new stuff without breaking any existing documentation.

Best,
Gabriel Fernandes


From: Jim Amsden <jamsden@...>
Sent: Monday, July 1, 2019 3:58 PM
To: oslc-op@...
Cc: Gabriel Fernandes
Subject: Re: Re: [oslc-op] 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

Jim Amsden
 

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

Andrii Berezovskyi
 

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


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


Determine ho to publish Open Project specifications

Jim Amsden
 

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


Re: OSLC Specs Search

Axel Reichwein
 

Very cool! Thanks Andrew!


Re: Submitting the Quality Management Open Project Specification for public review

Andrii Berezovskyi
 

Very much appreciated, Chet! Have a nice weekend!

--
/Andrew
(from phone)



On Fri, Jun 28, 2019 at 8:03 PM +0200, "Chet Ensign" <chet.ensign@...> wrote:

Slowly but surely, I am getting oriented to where we are and catching up... 

On Thu, Jun 27, 2019 at 5:48 PM Andrii Berezovskyi <andriib@...> wrote:

I want to make sure I got this right, so let me make some comments and please correct me if I got this wrong in any way:

1) We are not submitting a spec for public review.

The OP rules do not require that so yes, that is fine. 

Instead, OP maintainers are preparing to ask the PGB to approve a Project Specification Draft 04 (we will skip PSDs 1 to 3 for Core to avoid any confusion with the CSPRDs 1 to 3 published by the Core TC, I don't know how many CSPRDs were published by the Domains TC for the QM spec). The only approval required for this is from PGB, with 14 days notice.

Correct. And approving it as PSD04 is fine.  

No approval from OASIS administrator is needed: https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specifications, §13.3 (not sure what does the term Designated Branch refers to).

Right, no approval needed from us. By 'designated branch' we were trying to say, basically, you should approve a labeled branch that  people can get back to later if they want to review the evolution of the TC work product.  

2) We do not have to use OASIS infrastructure to publish a PSD or to produce PDFs. We are planning to make a PR with the changes to the document revision, status and links and tag it on Github with a tag 'psd-04', for example.

Correct. 


3) I suggest to have all comments on the PSDs to be submitted as Github issues.

That is certainly a good way to do it process-wise. But personally, I wouldn't rule out that you might get good comments via the email list.   

4) The specification will not be provided under the Apache 2.0 license. Apache license is best suited for the source code. The text of the spec will be CC BY 4.0 licensed (Attribution 4.0 International). Vocabulary and OSLC Shape machine-readable documents will be provided under the Apache 2.0 license. Did I miss something?

That is fine - your call.  


Also, we had some discussion in the OP call regarding the naming of the specs and publishing of the PDFs. Chet, we are still working it out but I would appreaciate if you follow/participate in https://github.com/oslc-op/oslc-admin/issues/6.

Yes, I have been working my way through the discussions. I definitely have some questions to discuss with you there. Will get those thoughts together today.  


/Andrew

From: Chet Ensign <chet.ensign@...>
Sent: 26 June 2019 23:51
To: Jim Amsden
Cc: Andrii Berezovskyi
Subject: Re: Submitting the Quality Management Open Project Specification for public review
 
Jim, Andrew, I'm spending the afternoon catching up on all this. Apologies for falling behind... 

On Mon, Jun 10, 2019 at 2:00 PM Jim Amsden <jamsden@...> wrote:

1. Make sure the oslc-op@... mailing list is working so that we can collaborate appropriately.
Yes and that's done.  

2. Finalize the text for the Status section of the Open Project in ReSpec. I suggest the following content:
Yes, this section looks good.  

This document was last revised or approved by the OASIS OSLC Open Projecton the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document.

Comments on this specification can be sent to the OSLC Open Project’s public comment list oslc-op@..., after subscribing to it by following the instructions in “Contributing” at https://github.com/oslc-op/oslc-admin/blob/master/CONTRIBUTING.md.
That sounds right. I'll look at the text in CONTRIB now and may make a suggestion via pull request.  

This specification is being provided under the Apache 2.0 License and Attribution 4.0 International.
Suggest linking these to the licenses. Apache 2.0 - https://www.apache.org/licenses/LICENSE-2.0 - CC-BY 4.0 -  https://creativecommons.org/licenses/by/4.0/legalcode
 
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

3. The https://github.com/oslc-op/oslc-admin/blob/master/CONTRIBUTING.mdsection does not describe the process for subscribing to the oslc-op mailing list - assuming that's what will be used for public review comments, and does not yet describe the feedback licensing terms. Is there a link we should include in the Status section that describes the feedback process and licensing implications? Something similar to https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=oslc-corebut for open projects?
Not yet. Let me sort that out.  

4. The content of the Notices section needs to be finalized. Here's what we currently have

Copyright © OASIS Open 20189. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Open Project (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Project Specification or OASIS Standard, to notify OASIS TCOpen Project (OP) Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode licensing of the OASIS Open Project that produced this specification.

OASIS invites any party to contact the OASIS TC OP Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode licensing of the OASIS Open Project that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Open Project can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Project Specification or OASIS Standard, can be obtained from the OASIS TC OP Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.


5. Determine a process for publishing open project specifications on OASIS
  • Determine the URL pattern for the published specifications
Yes. Still TBD. 
  • Publish rendered specifications to OASIS
I'm not sure what you mean by 'publish' here. Hand them off to us to load and announce? 
I'm not sure of the import of this either. Are the resource shapes something different from the QM Spec?  

Anything else?

--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575



--

/chet 
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: +1 201-341-1393 


--

/chet 
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: +1 201-341-1393 


Re: Submitting the Quality Management Open Project Specification for public review

Chet Ensign
 

Slowly but surely, I am getting oriented to where we are and catching up... 

On Thu, Jun 27, 2019 at 5:48 PM Andrii Berezovskyi <andriib@...> wrote:

I want to make sure I got this right, so let me make some comments and please correct me if I got this wrong in any way:

1) We are not submitting a spec for public review.

The OP rules do not require that so yes, that is fine. 

Instead, OP maintainers are preparing to ask the PGB to approve a Project Specification Draft 04 (we will skip PSDs 1 to 3 for Core to avoid any confusion with the CSPRDs 1 to 3 published by the Core TC, I don't know how many CSPRDs were published by the Domains TC for the QM spec). The only approval required for this is from PGB, with 14 days notice.

Correct. And approving it as PSD04 is fine.  

No approval from OASIS administrator is needed: https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specifications, §13.3 (not sure what does the term Designated Branch refers to).

Right, no approval needed from us. By 'designated branch' we were trying to say, basically, you should approve a labeled branch that  people can get back to later if they want to review the evolution of the TC work product.  

2) We do not have to use OASIS infrastructure to publish a PSD or to produce PDFs. We are planning to make a PR with the changes to the document revision, status and links and tag it on Github with a tag 'psd-04', for example.

Correct. 


3) I suggest to have all comments on the PSDs to be submitted as Github issues.

That is certainly a good way to do it process-wise. But personally, I wouldn't rule out that you might get good comments via the email list.   

4) The specification will not be provided under the Apache 2.0 license. Apache license is best suited for the source code. The text of the spec will be CC BY 4.0 licensed (Attribution 4.0 International). Vocabulary and OSLC Shape machine-readable documents will be provided under the Apache 2.0 license. Did I miss something?

That is fine - your call.  


Also, we had some discussion in the OP call regarding the naming of the specs and publishing of the PDFs. Chet, we are still working it out but I would appreaciate if you follow/participate in https://github.com/oslc-op/oslc-admin/issues/6.

Yes, I have been working my way through the discussions. I definitely have some questions to discuss with you there. Will get those thoughts together today.  


/Andrew

From: Chet Ensign <chet.ensign@...>
Sent: 26 June 2019 23:51
To: Jim Amsden
Cc: Andrii Berezovskyi
Subject: Re: Submitting the Quality Management Open Project Specification for public review
 
Jim, Andrew, I'm spending the afternoon catching up on all this. Apologies for falling behind... 

On Mon, Jun 10, 2019 at 2:00 PM Jim Amsden <jamsden@...> wrote:

1. Make sure the oslc-op@... mailing list is working so that we can collaborate appropriately.
Yes and that's done.  

2. Finalize the text for the Status section of the Open Project in ReSpec. I suggest the following content:
Yes, this section looks good.  

This document was last revised or approved by the OASIS OSLC Open Projecton the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document.

Comments on this specification can be sent to the OSLC Open Project’s public comment list oslc-op@..., after subscribing to it by following the instructions in “Contributing” at https://github.com/oslc-op/oslc-admin/blob/master/CONTRIBUTING.md.
That sounds right. I'll look at the text in CONTRIB now and may make a suggestion via pull request.  

This specification is being provided under the Apache 2.0 License and Attribution 4.0 International.
Suggest linking these to the licenses. Apache 2.0 - https://www.apache.org/licenses/LICENSE-2.0 - CC-BY 4.0 -  https://creativecommons.org/licenses/by/4.0/legalcode
 
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

3. The https://github.com/oslc-op/oslc-admin/blob/master/CONTRIBUTING.mdsection does not describe the process for subscribing to the oslc-op mailing list - assuming that's what will be used for public review comments, and does not yet describe the feedback licensing terms. Is there a link we should include in the Status section that describes the feedback process and licensing implications? Something similar to https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=oslc-corebut for open projects?
Not yet. Let me sort that out.  

4. The content of the Notices section needs to be finalized. Here's what we currently have

Copyright © OASIS Open 20189. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Open Project (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Project Specification or OASIS Standard, to notify OASIS TCOpen Project (OP) Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode licensing of the OASIS Open Project that produced this specification.

OASIS invites any party to contact the OASIS TC OP Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode licensing of the OASIS Open Project that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Open Project can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Project Specification or OASIS Standard, can be obtained from the OASIS TC OP Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.


5. Determine a process for publishing open project specifications on OASIS
  • Determine the URL pattern for the published specifications
Yes. Still TBD. 
  • Publish rendered specifications to OASIS
I'm not sure what you mean by 'publish' here. Hand them off to us to load and announce? 
I'm not sure of the import of this either. Are the resource shapes something different from the QM Spec?  

Anything else?

--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575



--

/chet 
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: +1 201-341-1393 


--

/chet 
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: +1 201-341-1393 


Re: AA warning on the RM 2.1 CSPRD01

Chet Ensign
 

Whoops. Thanks for that catch. We add that file briefly while we are QA'ing files after copying them from our staging server. We remove it before announcing the publication to everyone. Looks like we missed that step on this file. Paul, can you remove that please? 

Again, thanks...

/chet

On Thu, Jun 27, 2019 at 5:47 PM Andrii Berezovskyi <andriib@...> wrote:
Hello Chet,

What does this notice mean? https://docs.oasis-open.org/oslc-domains/oslc-rm/v2.1/csprd01/AA-README-Warning-Do-Not-Download.txt

--
–Andrew.



--

/chet 
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: +1 201-341-1393 


Re: OSLC Specs Search

Jim Amsden
 

Very Cool!!

Thanks for doing this.


--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575




From:        "Andrii Berezovskyi" <andriib@...>
To:        "oslc-op@..." <oslc-op@...>
Date:        06/28/2019 08:40 AM
Subject:        [EXTERNAL] [oslc-op] OSLC Specs Search
Sent by:        oslc-op@...




Hi,

I have set up a Custom Google Search engine over our specs:
https://forum.open-services.net/t/oslc-specs-search/275

--
–Andrew.









OSLC Specs Search

Andrii Berezovskyi
 

Hi,

I have set up a Custom Google Search engine over our specs: https://forum.open-services.net/t/oslc-specs-search/275

--
–Andrew.


Re: Next steps for OSLC OP Specifications

Andrii Berezovskyi
 

And this wow message itself took just under 8h...

--
/Andrew
(from phone)



On Fri, Jun 28, 2019 at 7:08 AM +0200, "Andrii Berezovskyi" <andriib@...> wrote:

Wow, it took 3 hours for this email to hit the list! What’s wrong with this mailing list?

--
/Andrew
(from phone)



On Thu, Jun 27, 2019 at 11:47 PM +0200, "Andrii Berezovskyi" <andriib@...> wrote:

Thanks! I would expect we produce only one PS in the end?

--
/Andrew
(from phone)



On Thu, Jun 27, 2019 at 8:24 PM +0200, "Jim Amsden" <jamsden@...> wrote:

This same content is captured in https://github.com/oslc-op/oslc-specs/issues/56but is included in an email to the oslc-op mailing list to ensure wider distribution:

Here's a summary of an OP project specification lifecycle:
        1        PGB can with 14 day notice vote to create a Project Specification Draft (PSD) revision anytime, and simply tags it in the repo, nothing is published
        2        Project Specification Draft can with 14 day notice be promoted to Project Specification (PS) by PGB Special Majority Vote, subject to specification conformance review by OASIS OP Admin
        3        Project Specification can be promoted to OASIS Standard
        i        With 3 statements of use, Submission of a Candidate OASIS Standard (COS) to the TC Administrator,
        ii        Completion of a public review lasting a minimum of 60 days, and
        iii        A call for consent to approve the COS as OASIS Standard.
        iv        A potential single, second call for consent after addressing negative comments.
See https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specificationsfor details.

In order to proceed we need to do the following:
        1.        
Finish any document edits and ReSpec changes
        2.        
Produce HTML and PDF documents and review for template conformance with Chet
        3.        
Schedule a PGB vote to create Project Specification Drafts (PSD) for all documents
        4.        
Schedule Special Majority Vote two weeks later to promote PSDs to Project Specifications (PS) and publish PS HTML and PDF revisions to OASIS Library
        5.        
For Core, AM, CM, QM and RM specs, collect 3 statements of use and schedule Special Majority Vote to promote those Project Specifications to COS and submit to 60 day public review
        6.        
Respond to review and Call for Consent issues as needed to progress to OASIS Standard

--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575


Re: Next steps for OSLC OP Specifications

Andrii Berezovskyi
 

Wow, it took 3 hours for this email to hit the list! What’s wrong with this mailing list?

--
/Andrew
(from phone)



On Thu, Jun 27, 2019 at 11:47 PM +0200, "Andrii Berezovskyi" <andriib@...> wrote:

Thanks! I would expect we produce only one PS in the end?

--
/Andrew
(from phone)



On Thu, Jun 27, 2019 at 8:24 PM +0200, "Jim Amsden" <jamsden@...> wrote:

This same content is captured in https://github.com/oslc-op/oslc-specs/issues/56but is included in an email to the oslc-op mailing list to ensure wider distribution:

Here's a summary of an OP project specification lifecycle:
        1        PGB can with 14 day notice vote to create a Project Specification Draft (PSD) revision anytime, and simply tags it in the repo, nothing is published
        2        Project Specification Draft can with 14 day notice be promoted to Project Specification (PS) by PGB Special Majority Vote, subject to specification conformance review by OASIS OP Admin
        3        Project Specification can be promoted to OASIS Standard
        i        With 3 statements of use, Submission of a Candidate OASIS Standard (COS) to the TC Administrator,
        ii        Completion of a public review lasting a minimum of 60 days, and
        iii        A call for consent to approve the COS as OASIS Standard.
        iv        A potential single, second call for consent after addressing negative comments.
See https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specificationsfor details.

In order to proceed we need to do the following:
        1.        
Finish any document edits and ReSpec changes
        2.        
Produce HTML and PDF documents and review for template conformance with Chet
        3.        
Schedule a PGB vote to create Project Specification Drafts (PSD) for all documents
        4.        
Schedule Special Majority Vote two weeks later to promote PSDs to Project Specifications (PS) and publish PS HTML and PDF revisions to OASIS Library
        5.        
For Core, AM, CM, QM and RM specs, collect 3 statements of use and schedule Special Majority Vote to promote those Project Specifications to COS and submit to 60 day public review
        6.        
Respond to review and Call for Consent issues as needed to progress to OASIS Standard

--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575


Re: Submitting the Quality Management Open Project Specification for public review

Andrii Berezovskyi
 

Thanks a lot, Chet!


I want to make sure I got this right, so let me make some comments and please correct me if I got this wrong in any way:


1) We are not submitting a spec for public review. Instead, OP maintainers are preparing to ask the PGB to approve a Project Specification Draft 04 (we will skip PSDs 1 to 3 for Core to avoid any confusion with the CSPRDs 1 to 3 published by the Core TC, I don't know how many CSPRDs were published by the Domains TC for the QM spec). The only approval required for this is from PGB, with 14 days notice. No approval from OASIS administrator is needed: https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specifications, §13.3 (not sure what does the term Designated Branch refers to).


2) We do not have to use OASIS infrastructure to publish a PSD or to produce PDFs. We are planning to make a PR with the changes to the document revision, status and links and tag it on Github with a tag 'psd-04', for example.


3) I suggest to have all comments on the PSDs to be submitted as Github issues.


4) The specification will not be provided under the Apache 2.0 license. Apache license is best suited for the source code. The text of the spec will be CC BY 4.0 licensed (Attribution 4.0 International). Vocabulary and OSLC Shape machine-readable documents will be provided under the Apache 2.0 license. Did I miss something?


Also, we had some discussion in the OP call regarding the naming of the specs and publishing of the PDFs. Chet, we are still working it out but I would appreaciate if you follow/participate in https://github.com/oslc-op/oslc-admin/issues/6.


/Andrew

From: Chet Ensign <chet.ensign@...>
Sent: 26 June 2019 23:51
To: Jim Amsden
Cc: Andrii Berezovskyi
Subject: Re: Submitting the Quality Management Open Project Specification for public review
 
Jim, Andrew, I'm spending the afternoon catching up on all this. Apologies for falling behind... 

On Mon, Jun 10, 2019 at 2:00 PM Jim Amsden <jamsden@...> wrote:

1. Make sure the oslc-op@... mailing list is working so that we can collaborate appropriately.
Yes and that's done.  

2. Finalize the text for the Status section of the Open Project in ReSpec. I suggest the following content:
Yes, this section looks good.  

This document was last revised or approved by the OASIS OSLC Open Projecton the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document.

Comments on this specification can be sent to the OSLC Open Project’s public comment list oslc-op@..., after subscribing to it by following the instructions in “Contributing” at https://github.com/oslc-op/oslc-admin/blob/master/CONTRIBUTING.md.
That sounds right. I'll look at the text in CONTRIB now and may make a suggestion via pull request.  

This specification is being provided under the Apache 2.0 License and Attribution 4.0 International.
Suggest linking these to the licenses. Apache 2.0 - https://www.apache.org/licenses/LICENSE-2.0 - CC-BY 4.0 -  https://creativecommons.org/licenses/by/4.0/legalcode
 
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.

3. The https://github.com/oslc-op/oslc-admin/blob/master/CONTRIBUTING.mdsection does not describe the process for subscribing to the oslc-op mailing list - assuming that's what will be used for public review comments, and does not yet describe the feedback licensing terms. Is there a link we should include in the Status section that describes the feedback process and licensing implications? Something similar to https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=oslc-corebut for open projects?
Not yet. Let me sort that out.  

4. The content of the Notices section needs to be finalized. Here's what we currently have

Copyright © OASIS Open 20189. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Open Project (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Project Specification or OASIS Standard, to notify OASIS TCOpen Project (OP) Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode licensing of the OASIS Open Project that produced this specification.

OASIS invites any party to contact the OASIS TC OP Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode licensing of the OASIS Open Project that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Open Project can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Project Specification or OASIS Standard, can be obtained from the OASIS TC OP Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.


5. Determine a process for publishing open project specifications on OASIS
  • Determine the URL pattern for the published specifications
Yes. Still TBD. 
  • Publish rendered specifications to OASIS
I'm not sure what you mean by 'publish' here. Hand them off to us to load and announce? 
I'm not sure of the import of this either. Are the resource shapes something different from the QM Spec?  

Anything else?

--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575



--

/chet 
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Mobile: +1 201-341-1393 


Re: Next steps for OSLC OP Specifications

Andrii Berezovskyi
 

Thanks! I would expect we produce only one PS in the end?

--
/Andrew
(from phone)



On Thu, Jun 27, 2019 at 8:24 PM +0200, "Jim Amsden" <jamsden@...> wrote:

This same content is captured in https://github.com/oslc-op/oslc-specs/issues/56but is included in an email to the oslc-op mailing list to ensure wider distribution:

Here's a summary of an OP project specification lifecycle:
        1        PGB can with 14 day notice vote to create a Project Specification Draft (PSD) revision anytime, and simply tags it in the repo, nothing is published
        2        Project Specification Draft can with 14 day notice be promoted to Project Specification (PS) by PGB Special Majority Vote, subject to specification conformance review by OASIS OP Admin
        3        Project Specification can be promoted to OASIS Standard
        i        With 3 statements of use, Submission of a Candidate OASIS Standard (COS) to the TC Administrator,
        ii        Completion of a public review lasting a minimum of 60 days, and
        iii        A call for consent to approve the COS as OASIS Standard.
        iv        A potential single, second call for consent after addressing negative comments.
See https://www.oasis-open.org/policies-guidelines/open-projects-process#project-specificationsfor details.

In order to proceed we need to do the following:
        1.        
Finish any document edits and ReSpec changes
        2.        
Produce HTML and PDF documents and review for template conformance with Chet
        3.        
Schedule a PGB vote to create Project Specification Drafts (PSD) for all documents
        4.        
Schedule Special Majority Vote two weeks later to promote PSDs to Project Specifications (PS) and publish PS HTML and PDF revisions to OASIS Library
        5.        
For Core, AM, CM, QM and RM specs, collect 3 statements of use and schedule Special Majority Vote to promote those Project Specifications to COS and submit to 60 day public review
        6.        
Respond to review and Call for Consent issues as needed to progress to OASIS Standard

--
Jim Amsden, Senior Technical Staff Member
ELM Quality Manager
919-525-6575

1041 - 1060 of 1072