Edit boilerplate to satisfy TAB-1652

[berezovskyi]

https://issues.oasis-open.org/projects/TAB/issues/TAB-1652?filter=allopenissues

Also the guidelines: http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html

[berezovskyi]

Cherry-picked this commit from #29 not to hold up bugfix release.

[berezovskyi]

@chet-ensign @OASIS-OP-Admin could you please help us navigate this? I initially thought the boilerplate was wrong only to find out that all of our conformance clauses in all specs are wrong and have to be combined into Conformance Targets (which I proposed earlier as OSLC Profiles, but that was supposed to be a totally different discussion). How much to we have to change?

[berezovskyi]

cc @jamsden

[chet-ensign]

Andrew, the short answer is that you don't *have* to change anything. The TAB - Jacques, I think - provided feedback on the conformance clauses based on his experience and expertise. It is up to you all whether you choose to act on them or not. The point of the conformance clauses is to spell out, for implementers, what conditions they have to meet for a specific implementation - a conformance target - to conform to the spec. If you claim to have a server, and the spec says it must do x, y, and z but your server only does x and z then it doesn't conform. The reason why that is important is that OASIS IPR protections only extend to conforming implementations. This obviously poses a problem for your implementers if they can't figure out what tests they have to pass. If it isn't clear that x, y, and z only apply to servers, you can see how things could get confusing. However, that is a call you - the experts in your field - must make. If you believe the clauses are sufficient for the people implementing your work, then you needn't take any action at all. If you think there is something that can be done better, then by all means, update the clauses accordingly. /chet

…

On Thu, Jan 9, 2020 at 1:07 PM Andrew Berezovskyi ***@***.***> wrote: cc @jamsden <https://github.com/jamsden> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#32?email_source=notifications&email_token=ACYUWRI7K7OKMNI3Y72CDKLQ45RVJA5CNFSM4KE4JSZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIRHEBA#issuecomment-572682756>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACYUWRNBLL3U56AKOI55BUTQ45RVJANCNFSM4KE4JSZA> .

-- /chet ---------------- Chet Ensign Chief Technical Community Steward OASIS: Advancing open source & open standards for the information society http://www.oasis-open.org Mobile: +1 201-341-1393

[jamsden]

There's a wide range of possibilities for expressing conformance. At one end, implementers would expect to have to implement everything marked with MUST in normative sections in the document. A the other end, a specification may have only one normative section that lists the specific conformance clauses that must be implemented. The former is inconvenient for implementers because the conformance text is distributed throughout a potentially large and complex document. The latter is inconvenient because brief conformance clauses in a table don't provide useful context for understanding them.

At OASIS guidance, and the MQTT spec as a guide, we tried to come up with something in the middle. We marked specific clauses in the document that had conformance implications, where you can see them in context. Then ReSpec collected these clauses in a single Conformance section that puts them all in one place, linking the two so it is easy to navigate from the table to the clause in context. These markers would also make it easy to use HTML DOM to automate linking from implementer test cases to the corresponding conformance clause.

In our case, we have not establish specific conformance levels for OSLC, favoring instead open world principles that everything is optional, but if an implementer choses to implement some capability, then the requirements are specified. So we may be misusing the notion of conformance and are really just summarizing requirements for features.

[berezovskyi]

Thanks to both Jim and Chet. As Jim said, all MUST statements shall be implemented. Currently, specs only target servers so there is no room for confusion to arise. Client guidance is only given in non-normative sections if any. Chet, the TAB issue in question is marked as high-priority. We would rather not remove conformance clause numbers from the table, we wish to keep them numbered. Can you please check with TAB (as we have no permissions to leave comments) that it is ok to close the issue as wontfix?

…

-- /Andrew (from phone) On 9 Jan 2020, at 22:19, Jim Amsden <[email protected]<mailto:[email protected]>> wrote: There's a wide range of possibilities for expressing conformance. At one end, implementers would expect to have to implement everything marked with MUST in normative sections in the document. A the other end, a specification may have only one normative section that lists the specific conformance clauses that must be implemented. The former is inconvenient for implementers because the conformance text is distributed throughout a potentially large and complex document. The latter is inconvenient because brief conformance clauses in a table don't provide useful context for understanding them. At OASIS guidance, and the MQTT spec as a guide, we tried to come up with something in the middle. We marked specific clauses in the document that had conformance implications, where you can see them in context. Then ReSpec collected these clauses in a single Conformance section that puts them all in one place, linking the two so it is easy to navigate from the table to the clause in context. These markers would also make it easy to use HTML DOM to automate linking from implementer test cases to the corresponding conformance clause. In our case, we have not establish specific conformance levels for OSLC, favoring instead open world principles that everything is optional, but if an implementer choses to implement some capability, then the requirements are specified. So we may be misusing the notion of conformance and are really just summarizing requirements for features. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#32?email_source=notifications&email_token=AAAPZXQU4SV2XESNFBEZBP3Q46IFDA5CNFSM4KE4JSZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIR2IKI#issuecomment-572761129>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAAPZXWEC6JNW2EB244UAWLQ46IFDANCNFSM4KE4JSZA>.

[chet-ensign]

Andrew, I just added you to the TAB JIRA so that you can make any updates on the tickets that you want. Also, the comments from the TAB are no different than comments from any other reviewer. That it is the TAB doesn't mean that they put any extra obligations on the TC. You just need to track and report on the TC's decisions on resolutions as you do with any other comment received. On Thu, Jan 9, 2020 at 4:37 PM Andrew Berezovskyi <[email protected]> wrote:

…

Thanks to both Jim and Chet. As Jim said, all MUST statements shall be implemented. Currently, specs only target servers so there is no room for confusion to arise. Client guidance is only given in non-normative sections if any. Chet, the TAB issue in question is marked as high-priority. We would rather not remove conformance clause numbers from the table, we wish to keep them numbered. Can you please check with TAB (as we have no permissions to leave comments) that it is ok to close the issue as wontfix? -- /Andrew (from phone) On 9 Jan 2020, at 22:19, Jim Amsden ***@***.***<mailto: ***@***.***>> wrote: There's a wide range of possibilities for expressing conformance. At one end, implementers would expect to have to implement everything marked with MUST in normative sections in the document. A the other end, a specification may have only one normative section that lists the specific conformance clauses that must be implemented. The former is inconvenient for implementers because the conformance text is distributed throughout a potentially large and complex document. The latter is inconvenient because brief conformance clauses in a table don't provide useful context for understanding them. At OASIS guidance, and the MQTT spec as a guide, we tried to come up with something in the middle. We marked specific clauses in the document that had conformance implications, where you can see them in context. Then ReSpec collected these clauses in a single Conformance section that puts them all in one place, linking the two so it is easy to navigate from the table to the clause in context. These markers would also make it easy to use HTML DOM to automate linking from implementer test cases to the corresponding conformance clause. In our case, we have not establish specific conformance levels for OSLC, favoring instead open world principles that everything is optional, but if an implementer choses to implement some capability, then the requirements are specified. So we may be misusing the notion of conformance and are really just summarizing requirements for features. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub< #32?email_source=notifications&email_token=AAAPZXQU4SV2XESNFBEZBP3Q46IFDA5CNFSM4KE4JSZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIR2IKI#issuecomment-572761129>, or unsubscribe< https://github.com/notifications/unsubscribe-auth/AAAPZXWEC6JNW2EB244UAWLQ46IFDANCNFSM4KE4JSZA>. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#32?email_source=notifications&email_token=ACYUWRPKGL4LWXRB5MIEUJLQ46KJNA5CNFSM4KE4JSZKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIR35EY#issuecomment-572767891>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACYUWROUV5SQHY2BXGHQRNDQ46KJNANCNFSM4KE4JSZA> .

-- /chet ---------------- Chet Ensign Chief Technical Community Steward OASIS: Advancing open source & open standards for the information society http://www.oasis-open.org Mobile: +1 201-341-1393

[berezovskyi]

Closing as wontfix. @jamsden @ndjc please reopen if necessary.