Hi Joel, > .. I can draft an example of the kind of documentation ...
That's a great idea! Please feel free to submit pull requests. The doc directory is [3] Tsz-Wo [3] https://github.com/apache/ratis/tree/master/ratis-docs/src/site/markdown On Wed, Dec 24, 2025 at 2:45 PM Joel Shepherd <[email protected]> wrote: > 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. >> >> >> >>
