Details of Non-material change to CS01

[Tsutomu Kamimura <tomk@nanzan.jp>]

To whom it may concern:

This note is to describe the problem and its resolution that led to the request of special majority vote to approve committee specification CS01 of PROMCODE with non-material change.

The problem.

Andrii Berezovskyi posted a comment to the oslc-promoce-comment mailing list on  October 21, 2021 pointing out wrong anchors in promcode-shapes.html file. The comment is at https://lists.oasis-open.org/archives/oslc-promcode-comment/202110/msg00002.htm l.  In essense, the comment claims that the promcode-shapes.html document does not handle a URL of "document URL"#"resource name" properly. For example,   https://docs.oasis-open.org/oslc-promcode/promcode/v1.0/cs01/promcode-shapes.html#IssueColletion   does not take a brower to the section describing IssueCollection resource. 
PROMCODE TC investigated the issue and found out that this is caused by Pandoc tool that creates html sections with their ID attributes set with section names in all lowercase. TC also found out that the problem exists in other OSLC specification documents including Core, CM, CCM and AM. Therefore, this is not unque to PROMCODE and OSLC PGB should decide how to handle the issue. 

In the meantime, supporting the URL, i.e., "the document url#resource name" is useful in improving the usability of document, and PROMCODE TC discussed how we should handle the issue in PROMCODE. In  consultation with TC Admin Office, TC decided to use a request of non-material change to the CS01. TC has confirmed that the change is non-material since it does not affect the resource model of PROMCODE at all and the content the reader will see with a browser will be identical before and after the change. Yet, the usability of the html file will be improved with proper location of sections for resources. 


Details on the change to the source code of CS01

A change needed is to the source code of promcode-shapes.html of OSLC PROMCODE specification CS01 at https://docs.oasis-open.org/oslc-promcode/promcode/v1.0/cs01/promcode-shapes.html  

Two set of changes are needed

First set of change

PROMCODE introduces 14 classes of resources . These are Artifact, IssueCollection, Issue, ManagedItem, ManagedItemCollection, Measure, Measurement, Plan, Project, Report, Risk, RiskCollection, ScopeItem, and WorkItem. promcode-shapes.html file has a html section for each resource class. For example, in line 388, a section is defined as <section id="artifact" class="level3" typeof="bibo:Chapter" resource="#artifact" rel="bibo:Chapterâ> for Artifact. In this definition, id=âartifactâ defines the id of the section. This value should be the name of the resource, ie., âArtifact", not âartifactâ. The same changes are needed for other 13 resource classes. Their definitions are 

Issue at line 618
IssueCollection at line 508
ManagedItem at line 848
ManagedItemCollection at line 738
Measure at line 938
Measurement at line 1038
Plan at line 1128
Project at line 1238
Report at line 1378
Risk at line 1617
RiskCollection at line 1508
ScopeItem at line 1736
WorkItem at lie 1856

Current values of id attributes are set as the names of resource classes in lower case. They need to be changed to correct names that use upper case and lowercase.

Second set of change

With the above change, toc (table of content) section needs to change to reflect the above change. toc section is defined at line 340. In the definition, there is an anchor tag defined for each resource class. For example, for Artifact, the following anchor tag is defined.

<a href="" class="tocxref"><span class="secno">2.1 </span>Artifact</a>

With the above change, â#artifactâ needs to change to â#Artifactâ. 

The changes are needed for other 13 resource classes in this very long section definition.


I hope that this note clarifies the problem and the resolution requested

Regards,

Tom Kamimura