Hi Tsz-Wo - Thanks so much for responding.
As I'm thinking through this short thread, I'm realizing I'm not totally
sure what I'm looking for. :-)
Maybe we could try something like this: I can draft an example of the
kind of documentation that I think could be helpful and share it on this
list. Depending on the feedback, we can just leave it at that, or
iterate on it, and/or make it publicly available. My guess is that it
will need a few iterations since my knowledge of Raft and Ratis is
probably small compared to much of the community.
If that sounds worth trying, I can get started on it in the new year.
Thanks -- Joel.
On 12/24/2025 12:28 PM, Tsz-Wo Nicholas Sze wrote:
Hi Joel,
Thanks for using Ratis!
> ... A couple examples are how client-side actions map to state
machine invocations, how term indexes should be handled to minimize
the number of replays when a node restarts, other events from the Raft
layer that my state machine and application should be prepared to
handle, etc.
As you probably know, there are a few examples in [1]. If you have
some particular questions, please feel free to ask them here. Or, if
you have suggestions, we could add more code examples.
> ... does documentation like that (kind of a conceptual or
"programmer's guide" type documentation) exist? ...
There is a work-in-progress doc [2].
> ... does the community think there would be value in producing it?
Definitely. We should produce more docs.
Tsz-Wo
[1]
https://github.com/apache/ratis/tree/master/ratis-examples/src/main/java/org/apache/ratis/examples
[2] https://jojochuang.github.io/ratis-site/docs/overview/
On Tue, Dec 23, 2025 at 9:54 AM Joel Shepherd <[email protected]> wrote:
Hi - I've been working with Ratis-3.x for the past few weeks. One
ongoing challenge I've run into is that while the code is reasonably
documented, there's plenty of information about Raft, and there
are some
easy-to-find examples, I struggle with having a broader
understanding of
how all the pieces are supposed to work together. A couple
examples are
how client-side actions map to state machine invocations, how term
indexes should be handled to minimize the number of replays when a
node
restarts, other events from the Raft layer that my state machine and
application should be prepared to handle, etc.
Outside of example code, does documentation like that (kind of a
conceptual or "programmer's guide" type documentation) exist? If it
does, I'd appreciate a pointer to it and apologize for not finding it
myself. If not, does the community think there would be value in
producing it?
Thanks -- Joel.
