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. > > > >
