Uploaded image for project: 'OASIS OSLC Lifecycle Integration Core (OSLC Core) TC'
  1. OASIS OSLC Lifecycle Integration Core (OSLC Core) TC
  2. OSLCCORE-177

Core specification needs to have conformance clauses

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Component/s: Core
    • Labels:
      None
    • Proposal:
      Hide

      On Jun 7, I proposed the following to Chet:

      1. Add a conformance section based on guidance in http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html, at least in the core overview section that defines what we mean by conformance. I see that is already in section 4. OSLC Core 3.0 Capabilities (http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part1-overview/oslc-core-v3.0-csprd03-part1-overview.html#oslc-core-3.0-capabilities). But it could be called out in a separate section that applies to all the parts of the multi-part specification and be written more precisely. 

      Chet agreed and provided a link to how the AMQP TC did that their multi-part spec -> http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html#section-conformance 

      2. We can add <span class="conformanceClause">...</span> (or something similar) around any text we want to specifically call out as a conformance clause. This will take significant effort and additional review because we suspect not everyone will have the same idea what constitutes something that should be a conformance clause, and for what purpose: clarity in the document, highlighting implementation constraints, guiding automated testing, establishing specific test cases, etc.

      Chet responded that It would be great if this could be done, but I understand limited resources so you'll be fine with just #1 above. 

      3. We can enhance ReSpec to collect these clauses into a non-normative appendix that provides the clause number, and a link from the table to the clause in the body of the text. It looks like MQTT did something like that to automate the creation of Appendix B.

      Chet agreed this would be a lot of work and that #1 above would be sufficient. But note: For CSs, they'll need to add conformance clause sections if they advance further to Candidate OASIS Standard.  

      Show
      On Jun 7, I proposed the following to Chet: 1. Add a conformance section based on guidance in http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html , at least in the core overview section that defines what we mean by conformance. I see that is already in section 4. OSLC Core 3.0 Capabilities ( http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part1-overview/oslc-core-v3.0-csprd03-part1-overview.html#oslc-core-3.0-capabilities ). But it could be called out in a separate section that applies to all the parts of the multi-part specification and be written more precisely.  Chet agreed and provided a link to how the AMQP TC did that their multi-part spec ->  http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html#section-conformance   2. We can add <span class="conformanceClause">...</span> (or something similar) around any text we want to specifically call out as a conformance clause. This will take significant effort and additional review because we suspect not everyone will have the same idea what constitutes something that should be a conformance clause, and for what purpose: clarity in the document, highlighting implementation constraints, guiding automated testing, establishing specific test cases, etc. Chet responded that It would be great if this could be done, but I understand limited resources so you'll be fine with just #1 above.  3. We can enhance ReSpec to collect these clauses into a non-normative appendix that provides the clause number, and a link from the table to the clause in the body of the text. It looks like MQTT did something like that to automate the creation of Appendix B. Chet agreed this would be a lot of work and that #1 above would be sufficient. But note: For CSs, they'll need to add conformance clause sections if they advance further to Candidate OASIS Standard.   
    • Resolution:
      Hide

      We will add a conformance section based on guidance in http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html, and using the AMQP multi-part spec  as a guide (http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html#section-conformance)  at least in the core overview section that defines what we mean by conformance.

      This can leverage content in section 4. OSLC Core 3.0 Capabilities (http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part1-overview/oslc-core-v3.0-csprd03-part1-overview.html#oslc-core-3.0-capabilities). But it could be called out in a separate section that applies to all the parts of the multi-part specification and be written more precisely. 

      Show
      We will add a conformance section based on guidance in http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html , and using the AMQP multi-part spec  as a guide ( http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html#section-conformance )  at least in the core overview section that defines what we mean by conformance. This can leverage content in section 4. OSLC Core 3.0 Capabilities ( http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part1-overview/oslc-core-v3.0-csprd03-part1-overview.html#oslc-core-3.0-capabilities ). But it could be called out in a separate section that applies to all the parts of the multi-part specification and be written more precisely. 

      Description

      Chet and Paul noticed that the Requirements Management and Core speca do not have conformance clauses. 

      OASIS can publish CSDs without conformance clauses but OASIS rules require that the conformance clauses section be in place once work goes out for public review.

      The requirement is documented in paragraph 2.2.6 of +https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26#workProdComponents+

        Attachments

          Activity

            People

            • Assignee:
              jamsden James Amsden
              Reporter:
              jamsden James Amsden
            • Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated: