Should we stop track changes since JSON-LD 1.0?

[pchampin]

This spec (as well as JSON-LD 1.1 Syntax and JSON-LD 1.1 Framing) has an option, in §1.1 How to Read this Document, to highlight all the changes that were made compared to JSON-LD 1.0.

I would argue that we should drop this. First, because it is quite tedious to add the class change to any part of the document we modify (or any part we add). Second, because it would be even more tedious if we wanted to show instead (or in addition) the changes between 1.1 and 1.2, and why shouldn't we if we go down that path?

We already have a number of Change Log sections, I think that should be enough.

[niklasl]

I tend to agree with this. The overhead of maintaining it should be contrasted with how to best help implementers to update their algorithms. If we need to refactor something (e.g. for solving #558), I cannot readily tell how to best convey the change. While the Change Log mightn't be the best form, I also suspect <ins>/<del> would be similarly suboptimal. And we do need a Change Log, so we should focus on ensuring that it is as useful as possible.

Examples clearly showing version-tagged features (including changed behavior) are probably more usable (especially for data authors). That, and/or incorporating the examples in json-ld-syntax directly as tests (factored out as file using data-include in ReSpec). I also looked a bit at categorizing the test suite more, so that one could test separate features.

[niklasl]

Aside: I also started TRLD to have a code base being close to 1:1 with the algorithms; a diff on that can be another way to help display the differences. It is in type-annotated Python, but also transpiled to Java and JS. If that's not good enough, an INFRA-like "plain English" transpiler might be doable (or let an LLM do it; as long as proof-reading the results doesn't take even more time)...

[anatoly-scherbakov]

• Added a very small PR for https://github.com/w3c/json-ld-syntax: Remove the <ins> tag json-ld-syntax#479
• I think https://github.com/w3c/json-ld-framing does not have these tags, it would seem.