-
Notifications
You must be signed in to change notification settings - Fork 33
Disambiguation between Integration and Publication #736
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is kinda covered up in the #Publishing
section:
An entry is considered published once it is committed to by a published Checkpoint (i.e. a published Checkpoint's size is larger than the entry's assigned index).
But it's not a bad idea to stress the point again here.
I've suggested a small tweak in wording to bring it closer into line with publication being mainly about checkpoints to avoid the potential for any misinterpretation/confusion about static resources appearing before a checkpoint has been successfully published. Have a look and see what you think.
As discussed above in [Integration](#integration) and [Publishing](#publishing), | ||
sequenced entries will be first _asynchronously_ integrated into the log, and | ||
then published on the read API by a second _asynchronous_ process. Some | ||
personalities may need to block until this has been performed, e.g. because they | ||
will provide the requester with an inclusion proof, which requires integration | ||
and publication. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As discussed above in [Integration](#integration) and [Publishing](#publishing), | |
sequenced entries will be first _asynchronously_ integrated into the log, and | |
then published on the read API by a second _asynchronous_ process. Some | |
personalities may need to block until this has been performed, e.g. because they | |
will provide the requester with an inclusion proof, which requires integration | |
and publication. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication) | |
As discussed above in [Integration](#integration) and [Publishing](#publishing), | |
sequenced entries will be _asynchronously_ integrated into the log, with a new `checkpoint` committing to these entries being published periodically by another asynchronous process. | |
Some personalities may need to block until this has been performed, e.g. because they will provide the requester with an inclusion proof, which requires both then integration of the entry and the publication of a new checkpoint to have completed. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! More than stressing it out a second time, I think that the current phrasing is misleading: it suggests to wait for entries to be integrated and available, but that's not enough, one should really wait for a checkpoint to be published.
I like your wording better. I think that re-explaining the whole wheel every time is a bit cumbersome though. It makes sense here because we need to leave no room for confusion. I think that the concept of "publishing an entry" is relatively new, and I had not realized that it was already used in the Publishing section. If my understanding is correct, we use to refer to it as "integration", which included the "publication" part, but they have now been split in two.
Should we start using "entry publication" more broadly as part of the append lifecycle? Would there be a better word than "publishing" to avoid confusion with the fact that entries are already publicly available before being published? "entries commitment/entries are committed to"? I'm interested for the context of this PR, but also in general when speaking about log.
As discussed above in [Integration](#integration) and [Publishing](#publishing), | |
sequenced entries will be first _asynchronously_ integrated into the log, and | |
then published on the read API by a second _asynchronous_ process. Some | |
personalities may need to block until this has been performed, e.g. because they | |
will provide the requester with an inclusion proof, which requires integration | |
and publication. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication) | |
As discussed above in [Integration](#integration) and [Publishing](#publishing), | |
sequenced entries will be {published/committed to} _asynchronously_: they will be integrated into the log, and a new `checkpoint` committing to these entries will be published on a clock by another asynchronous process. | |
Some personalities may need to block until this has been performed, e.g. because they will provide the requester with an inclusion proof, which requires both then integration of the entry and the publication of a new checkpoint to have completed. Such personalities are recommended to use [Synchronous Publication](#synchronous-publication) |
Personalities that need to wait should wait for a checkpoint to be published, rather than simple integration. For ease of writing, I think that it's okay to consider that "entries are published" only and only when "checkpoint covering these entries" has been published (even if the entries will be made public before then).