Docs/terminology for expected revision

[wiegell]

I have met all of these in the docs/source:

• Expected revision
• Prepare position
• Commit position
• Stream revision
• Next expected version
• Current version
• Current revision
• Stream position

It's not easy to tell them apart, since they are not explicitly documented. I suspect many of them mean the same. The revision concept is quite central to EventStore IMO, but it is difficult to get a grasp of when the documentation of it is vague. I would suggest you settle on a terminlogy, document it clearly and then make the libraries adhere to that terminology too.

Thanks in advance

[alexeyzimarev]

While it is being done, I can write things here.

Term	What is it
Expected revision	What to you expect the stream revision would be when you append events there. If the revision doesn't match, the stream has been updated since you've read it and it causes "wrong expected revision" error. It's used for optimistic concurrency
Prepare position	It's been used before with explicit transactions. As we don't support them anymore, this should be always the same as the commit position
Commit position	Byte position of an event in the log. It's useful for subscribing to $all as it doesn't have logical sequence.
Stream revision	It's what it is, previously known as "stream version". When you append an event to a new stream, its revision will be zero. Append one more event and you get revision 1. If you don't truncate streams, the revision is the number of events in the stream minus one. When you truncate, the revision doesn't change and keeps incrementing, so it's, again, a reliable stream version. You can also see this as the number of events that were ever appended to the stream, minus one.
Next expected version	When you execute an append, the append result will return you the stream revision after the append, so you can use it as the current stream revision for consequent appends to the same stream if you have any. It allows you to skip reading the stream revision if you have multiple appends to the same stream being executed one by one (not sure why).
Current version	Same as stream revision
Current revision	Same as stream revision
Stream position	It's used for stream reads and subscriptions. The place where you want to read or subscribe from. If you want to read from a stream starting from the tenth event, the stream position for that would be nine as event stream positions are zero-based. Stream position of the last event in the stream is the same as the stream revision. When you subscribe, it will start from a give position plus one.

[wiegell]

Great explanation, thanks alot. Some thoughts:

• Rename the places where "Current version" and "Current revision" are used to "Stream Revision"
• Rename "Prepare position" to "Commit position"
• Rename "Next expected version" to "Next expected revision"
• I forgot some terms also used "Event #" (admin gui), "Event Number" and "Event Revision" (go client). The explanation in the docs is OK, but i miss an explicit connection between "Event number" and "Stream revision" in the docs (that you can use an event number in a subsequent call as an expected revision). Also much of that information about stream revisions and how they behave on truncating is not in the client docs, but in the server docs (hidden in the "Features" section). I think a brief explanation about truncation and how it relates to stream revisions / eventnumbers is needed also in the client docs.
• I would suggest settling on either "Event Number" or "Event Revision".

[yordis]

Would it make sense to adopt https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag ... sorry to add to the mess 😓

[alexeyzimarev]

Rename "Prepare position" to "Commit position"

We can't do that because prepare position still exists in legacy databases, otherwise we would have already removed any notion of it.

"Event number" sounds correct. I think the terminology used in the Navigator app is correct, but we are open for suggestions for the upcoming Preview 2 of the app.

"Event revision" doesn't make sense as events are immutable and have no revisions. "Stream revision", on the other hand, is legit. Appending an event to a stream increases the stream revision by one.

[alexeyzimarev]

@yordis eTags are a bit different:

Entity tag that uniquely represents the requested resource. It is a string of ASCII characters placed between double quotes, like "675af34563dc-tr34".

The only unique identifiers of a resources in ESDB would be:

• Stream name combined with the event number. It only identifies an event.
• Stream name as the unique identifier of a stream

Stream revision cannot be an eTag or part of eTag as it doesn't identify the stream, it becomes the event eTag. Also, in most cases you aren't interested to get one event by its eTag. In most cases you either read the stream from the start or from a certain revision to the end of the stream, or read the stream backwards. Both cases can be classified as reading dynamic resources.

[yordis]

Yeah ... I was thinking only about the name, not the spec. I see multiple folks mapping the HTTP Etag directly into the expected version ... but I leave it to you, you know better. I'm looking forward to aligning on the topic!

[alexeyzimarev]

Rename "Next expected version" to "Next expected revision"

This makes sense btw