search

braid-org / braid-spec

Working area for Braid extensions to HTTP
https://braid.org
232 stars 16 forks source link

New Vocabulary for Versions and Updates #113

Closed toomim closed 9 months ago

toomim commented 11 months ago

This draft implements the proposed new vocabulary of https://github.com/braid-org/braid-spec/issues/102#issuecomment-1684571621, to address the ambiguity in the terms "Version" and "Body":

  1. Version ID: a single ID for a single edit, e.g. "8zsn2ha"
  2. Version: a set of IDs specifying a point in time, e.g. "8zsn2ha", or "8zsn2ha", "nsh3aj"
  3. Update: a data package to update a peer from one version to another
  4. Snapshot: the complete contents at a version, e.g. <html>Hello world!</html>

Impact on implementations:

toomim commented 11 months ago

In meeting-67:

toomim commented 11 months ago

Time-travel can go backwards. Asking for info in the past isn't an "update", it's a "backdate".

A couple alternatives to "Update" that can make sense going backwards:

CxRes commented 11 months ago

To summarize/suggest:

  1. Version ID -> Event ID for a single edit
  2. Version -> Version (Multiple edit Events change the Representation State to a new Version. A version ID could identify changes caused by multiple Events with different Event IDs).
  3. Update -> Change
  4. Snapshot -> (Representation) State
josephlacey commented 10 months ago

To summarize/suggest:

1. Version ID -> Event ID for a single edit
2. Version -> Version (Multiple edit Events change the Representation State to a new Version. A version ID could identify changes caused by multiple Events with different Event IDs).
3. Update -> Change
4. Snapshot -> (Representation) State

I'll second most of this, which seems to be where the consensus is headed. I don't quite get the idea of a version id in the second item, but I suspect that needs more discussion and is out of scope here.

'Snapshot' implies the time that's also implied by the event and change nomenclature. I probably lean toward keeping it. 'State' has become such a pregnant word that I hesitate some, but I'm not against it given that state is at the center of the spec. If the latter, I don't think 'Representation' is needed.

CxRes commented 10 months ago

@josephlacey Just to clarify what I meant:

I don't quite get the idea of a version id in the second item

Multiple edit events at any moment in time will create a one state (say when two clients PATCH at the same URL at the same time) with a new version. You need not have a Version-ID, but having some notion that the state can in principle have an identifier, different from the constituent events that create it, is nevertheless useful.

'State' has become such a pregnant word that I hesitate some,

It is a Representation of Resource State that is transferred in REST (which literally stands for Representational State Transfer). There is no getting away from this language.

I also think state is a natural way to speak of the "configuration" of a system at a particular time spread over space (how different physical objects are relative to each other, thus giving the system some information content). This is why state as a term is a natural fit. Snapshot on the other hand tend to refer to projections of a system. In my mind, a representation (what an observer has access to) is akin to a snapshot, whereas state is how the system exists (independent of the observer). We infer (or try to infer) the state of the system from one or more snapshot.

toomim commented 10 months ago

Chair: It sounds like we have consensus on the names that impact code (and thus interoperability):

And we have some good ideas for the 3 other terms, which only impact how us humans talk about code:

Since we seem to have consensus on the interop-critical words, I suggest we:

  1. Merge this PR for now
  2. Open a new issue to continue discussion of the remaining vocabulary, and target it for -04.

Does anyone object?

toomim commented 9 months ago

Okay, merging this PR!

We have consensus for Version and Current-Version, and we are continuing the conversation on Version ID, Update, and Snapshot in https://github.com/braid-org/braid-spec/issues/102 for a future revision.