First-Readthrough Nitpicks

[AljoschaMeyer]

Hi all,

I've collected some nitpicky feedback while reading the spec for the first time. Each outer list item quotes the spec, nested items are the comments.

• own, aside from from state synchronization
  • from
• HTTP can genrealize into a full
  • generalize
• A Version header is also allowed to contain multiple IDs, to describe the version of a merger:
  • this confuses me, doesn't the merge produce a single version as output?
• If a client or server does not specify a Parents header when transferring a new version, the recipient MAY presume that the most recent versions it has (the frontier of time) are the parents of the new version. It MAY also ignore or reject the update.
  • How do you create initial versions then? Empty parents header? Might help to explicitly state that here.
• There are two reasons to send an update as a patch:
  • two main reasons
• the leaves of the currently-known time DAG
  • "sinks" not "leaves"? (sorry for being pedantic, I spent too much time around digraph structure theoreticians...)

[toomim]

Thanks!

The first two bugs were recently fixed in git.

Merge Versions

Yes, a merge produces a single version as output. A version is specified as a set of IDs. Consider that any particular edit event can be specified with a unique ID. Any particular peer might have a different set of edit events, with a different set of event IDs, at any point in time. Thus, the version of state that the peer has can be specified as a set of event IDs.

In this spec, we've called these terms Version IDs and Versions, but perhaps that was confusing. Perhaps it would be clearer to call these concepts Event IDs and Versions? I believe that @CxRes and @dglittle have advocated for the latter.

Creating Initial Version

You can create an initial version with e.g.:

PUT /foo
version: "initial"
content-type: text/plain

Hello world!

It's possible that the server has a prior version, though. It's also possible for servers to create an initial version themselves without requiring a HTTP request to do so. I'm not sure if there's anything there that we need to specify here to ensure interoperability. But I'm also not understanding how the parents: header relates to new versions. Maybe there's something about that I should understand?

Two reasons to send an update as a patch

Can you think of any more reasons? I couldn't think of any when I wrote that.

Sinks vs. Leaves

I think of Sinks and Sources are terms used for flow graphs. Maybe there's a flow in time?

The term "Leaves" came from trees, and a DAG is a tree extended with multiple parents.

Another term we've been using is Frontier. That fits better with time. Maybe we should use that word here.

[AljoschaMeyer]

Merge versions: I see, a version is described by many ids. Which... the introductory paragraph actually states pretty clearly, I just missed it.

Creating Initial Version: Here I do believe the spec could be slightly more clear. It states that "version [...] has a set of parents", and that "Parents are specified with a Parents header in a PUT/PATCH/POST request or GET response". I would have interpreted that as a requirement that the empty set has to be encoded with a Parent header with zero strings, not by fully omitting the header. Some web searching tells me that empty headers are technically allowed but discouraged in practice maybe or maybe not? Seems like an explicit note on empty parent headers (and whether they have different semantics from no parent headers) could not hurt.

More patch reasons: Hmm, there must be some. More elegant implementations that do everything via patches (similar to how you can consider every element in a group as merely acting on other group members instead of being a value of interest in its own right)? But fair point, all the reasons I can come up with are rather artificial.

sinks vs leaves: Leaf is not really used aside from trees in the literature, whereas sink and source are standard digraph terminology: https://en.wikipedia.org/wiki/Directed_graph#Indegree_and_outdegree . But anyways, I'm not going to waltz into your project and insist on terminology changes.
Frontier is nice though, evokes exactly the right things (and does not evoke students incorrectly talking about leaves in digraphs, which might be part of why I pointed this out...).

[toomim]

empty parents:

Seems like an explicit note on empty parent headers (and whether they have different semantics from no parent headers) could not hurt.

Ah, yes, the behavior of empty parents is currently unspecified. Nobody has yet proposed a semantic for it, yet, though, so I know of nothing to specify on the topic. Thoughts are welcome.

sinks vs leaves:

1. Oh! I wasn't aware of that usage in Digraphs. Persuasive argument.
2. I thought I had used "leaves" in some of my past research groups with DAGs, but realized we were actually calling the nodes "terminals" vs. "non-terminals". This was for ambiguous parse trees, where a language has multiple paths up the tree, and it ends up being a DAG.

So right now, we've got three contender terms to replace "leaves":

• Sinks
• Frontier
• Terminals