Add changelog

[csarven]

Add properties and classes related to expressing "changelog" information available in technical reports, e.g., change subject, correction or change class (see below), and human-readable statement.

Changelogs are marked in documents such as Solid Protocol, Solid Notifications Protocol, Web Access Control. These reports include "a summary of editorial, substantive, and registry changes are classified using the W3C Process Document Classes of Changes".

A human-readable view of an example changelog of Solid Protocol, v0.11:

Example usage in Turtle connecting document, a particular requirement, with changelog information about that requirement:

@prefix spec: <http://www.w3.org/ns/spec#> .
@prefix : <https://solidproject.org/TR/2024/protocol-20240512#> .

<https://solidproject.org/TR/2024/protocol-20240512>
    spec:changelog :changelog ;
    spec:requirement :server-content-type-includes .

:changelog
    spec:change :d18392b9-8ffc-4264-a5a2-10e2da6fac32 .

:d18392b9-8ffc-4264-a5a2-10e2da6fac32
    a spec:Change ;
    spec:changeClass <https://www.w3.org/Consortium/Process/#class-4> ;
    spec:changeSubject :server-content-type-includes ;
    spec:statement "Add requirement for server to include Content-Type header field in messages with content."@en .

:server-content-type-includes
    spec:requirementLevel spec:MUST ;
    spec:requirementSubject :Server ;
    spec:statement "Server MUST generate a Content-Type header field in a message that contains content."@en .

Live SPARQL Query selecting changelog information across technical reports:

https://sparql.org/sparql?query=%0D%0APREFIX+spec%3A+%3Chttp%3A%2F%2Fwww.w3.org%2Fns%2Fspec%23%3E%0D%0ASELECT+%3Fdocument+%3Fchange+%3FchangeClass+%3FchangeSubject+%3Fstatement%0D%0AFROM+%0D%0A%3Chttp%3A%2F%2Frdf.greggkellogg.net%2Fdistiller%3Fcommand%3Dserialize%26format%3Drdfa%26output_format%3Dturtle%26url%3Dhttps%3A%252F%252Fsolidproject.org%252FTR%252Fprotocol%26raw%3E%0D%0AFROM+%0D%0A%3Chttp%3A%2F%2Frdf.greggkellogg.net%2Fdistiller%3Fcommand%3Dserialize%26format%3Drdfa%26output_format%3Dturtle%26url%3Dhttps%3A%252F%252Fsolidproject.org%252FTR%252Fwac%26raw%3E%0D%0AFROM+%0D%0A%3Chttp%3A%2F%2Frdf.greggkellogg.net%2Fdistiller%3Fcommand%3Dserialize%26format%3Drdfa%26output_format%3Dturtle%26url%3Dhttps%3A%252F%252Fsolidproject.org%252FTR%252Fnotifications-protocol%26raw%3E%0D%0AFROM+%0D%0A%3Chttp%3A%2F%2Frdf.greggkellogg.net%2Fdistiller%3Fcommand%3Dserialize%26format%3Drdfa%26output_format%3Dturtle%26url%3Dhttps%3A%252F%252Fsolidproject.org%252FED%252Fqa%26raw%3E%0D%0AFROM+%0D%0A%3Chttp%3A%2F%2Frdf.greggkellogg.net%2Fdistiller%3Fcommand%3Dserialize%26format%3Drdfa%26output_format%3Dturtle%26url%3Dhttps%3A%252F%252Fsolid.github.io%252Fwebid-profile%252F%26raw%3E%0D%0AWHERE%7B%0D%0A++%3Fdocument+spec%3Achangelog+%5B%0D%0A++++spec%3Achange+%3Fchange+%3B%0D%0A++%5D+.%0D%0A++%3Fchange%0D%0A++++spec%3AchangeClass+%3FchangeClass+%3B%0D%0A++++spec%3AchangeSubject+%3FchangeSubject+%3B%0D%0A++++spec%3Astatement+%3Fstatement+.%0D%0A%7D%0D%0AORDER+BY+%3Fdocument+%3FchangeClass+%3FchangeSubject&default-graph-uri=&output=xml&stylesheet=%2Fxml-to-html.xsl

An application (e.g., dokieli) making use of the changelog information by incorporating into a Conformance Requirements and Test Coverage table where a requirement URI is matched with a change subject URI:

[csarven]

When I introduced the new changelog structure in some of the Solid specs, I intentionally didn't mark the Add/Remove/Amend text because I figured it could be introduced later once the human-readable content and corresponding data model settled down. Perhaps now is as good a time as any? I'm open to reusing existing vocabularies with Addition/Removal/Amendment or introducing these into spec: now and later subclassing with specialised vocabularies.

I've looked at http://ontologi.es/doap-changeset (archived) and https://vocab.org/changeset/schema (and certainly drew inspiration from them) and probably a few other conceptually similar vocabularies, but they were either not dereferencing/abandoned or not quite the right fit for a technical document. I also looked at how W3C/IETF reports expressed changes. I preferred to have a simple vocabulary that can be consistent within the context of a technical document. Here we are.

The main reason for holding off on subclassing Change was that I had already wired Changes with W3C's correction classes via spec:changeClass, which generally covered the essence of changes. Its purpose communicates at a level above Add/Remove/Amend, but I think there is room for both.

With regards to reusing vocabularies in technical documents and what Spec Terms covers and where to draw the lines, it gets complicated. I've reused significant elements as much as possible in specs. There is certainly a lot of overlap with existing vocabularies, but there is also room to specialise. I'm happy to dive deeper into this discussion/work.

Missing is not wrong. So, as for this PR, we can incorporate spec:Addition, spec:Removal, spec:Amendment subclasses (and of course use them in some specs, which is easy-peasy) or revisit this at a later date. While information about changes is certainly not unique to specifications, it is not wrong to have Spec Terms express its own changes (whether extending other vocabularies or not) either.

:shrug:

[csarven]

@pchampin Can you please update http://www.w3.org/ns/spec with https://raw.githubusercontent.com/solid/vocab/main/spec.ttl

[pchampin]

done