Document the versioning process

[evanp]

In our meeting today, we agreed that we'd stick with our current system: use the regular https://www.w3.org/ns/activitystreams @context string, unless you need a version that stays bytewise identical every time, like for LDS, in which case use the versioning.

We agreed we'd document that process. I'd like to at least do it in the ERRATA document, and possibly in longer form somewhere else.

[evanp]

@sandhawke @cwebber

[evanp]

One way to do this would be to add to ERRATA.md something like:

5. Extensibility

In some circumstances, such as for [LDS], implementers may need to use a context URL for an immutable document. As extensions are added, we create new versioned documents, by version number and by hash. This version history is available [here].

[cwebber]

I like that.

[gobengo]

Don't want to distract, so maybe just down/up-vote this, but what about adding something like:

ActivityStreams consumers SHOULD consider any value starting with _____ equivalent to https://www.w3.org/ns/activitystreams for the purposes of identifying whether a JSON document is a valid ActivityStreams document. However, not all versions might be semantically valid, i.e. later versions of the context may define new terms.

[sandhawke]

@evanp I'd probably say "snapshot documents" instead of "versioned documents"... (in my mind, I can never tell whether "versioned" means the thing that changes or the thing that doesn't change.)

@gobengo Oh, yeah, good idea. Of course, the presence of that string doesn't prove it's valid -- it could broken in lots of ways -- but I get the idea. Maybe we can just approach by committing that all contexts starting with that string will be compatible versions, so then its becomes a MAY, the consumers MAY assume this is an AS document, and proceed with appropriate parsing stacks, if it uses a context starting with that string. Well... still, what's the point? Either you're doing plain-old-json, in which case you need exactly AS2 as in the Rec, or your doing RDF, in which you never have any reason to look at the context string. Right?

[nightpool]

Some discussion re: versioning, semantic meaning, and extensibility from IRC yesterday:

15:09 < nightpool> my concern though is that, as melody mentioned, in the
                   presence of a growing context, terms can even be ambiguous to a
                   JSON-LD compliant processor.
15:18 < cwebber2> nightpool: I'm not sure I follow... could you type a little
                  pseudo-example about what you're concerned about?
15:18 < nightpool> sure.
15:19 < nightpool> 1: server a publishes a document like
                   {"@context": ["https://myname.space", "https://www.w3.org/ns/activitystreams"], 
                   "term1": "whatever"}
15:19 < nightpool> this is valid because term1 is a property only
                   in myname.space.
15:19 < nightpool> 2. term1 gets added to the activitystreams namespace
15:20 < nightpool> now the old document (which may be getting passed around,
                   signed or cached or whatever) has totally different semantics
15:20 < cwebber2> nightpool: right
15:20 < nightpool> depending on which context you resolve from first,
                   which I dont even know without looking it up
15:21 < cwebber2> nightpool: I hear you... this is the danger of mutating
                  contexts basically
15:21 < cwebber2> I think this is semi-unlikely but the presence of semi- does
                  make it a concern
15:22 < cwebber2> because if it did happen
15:22 < cwebber2> it could be really bad
15:22 < cwebber2> especially if all your old documents had that
15:22 < nightpool> right

so i don't know if this is a problem only for people who want immutable documents—this seems to be something that could happen between any two servers in the presence of mutating contexts. (unless these servers are full JSON-LD processors and always look up the context before generating every single document, which sounds ludicrous)

i still don't know if I understand how versioned contexts solve this problem in practice either, especially for non-JSON-LD processors, which is a huge target use case for activitystreams.

[evanp]

OK! Thank you to @trwnh for finding the history doc:

https://www.w3.org/ns/activitystreams-history/

It looks like @plehegar dumped this whole dir out to a GitHub repo:

https://github.com/w3c/ns

Ideally, a PR to that repo would get the history document and updates pushed.

[evanp]

There is a Primer document that describes how we make snapshot versions when we add new terms and how to use the snapshot versions.

In terms of how we add new terms to the context, the Extensions Policy describes how and why we add extensions to the context doc.

I think this issue is resolved. We have further discussion about if and how to change this policy, but for now it's documented.

[trwnh]

shouldn't we make a formal note that for example the versioning process is something like "copy the context to 1.x.jsonld and also hash it and copy it to hash.jsonld, then send a PR to w3c/ns on github"? assuming that is indeed the process

EDIT: --> #589