Loric Brevet (Mar 02 2022 at 09:55): Loric Brevet (Mar 02 2022 at 09:55):Hi there!
I never took the time to correctly learn Rust, and Roc makes me want to come back to it. So I started again the learning path and having a real project to apply knowledge is really cool.
However, I feel (and I guess I am not the only one) that the codebase is difficult to approach from a beginner’s point of view (as any new codebase for large projects). And so I’d love to have someone (or some docs) showing me around!
But to go deeper into the thinking, I’d like to discuss what could be the way/or the format to facilitate the "entry ticket" for potential new contributors. As of today, there is a CONTRIBUTING.md doc in the repo that explains the first steps for the tooling. But maybe we can envision having something like a "tour of the codebase"? Some kind of guide that would explain at the high level the different pieces/modules in the code, and their responsibilities? That would help people like me to find where to look for when trying to contribute to "beginner’s issues" (and maybe that could benefit experienced people also).
Or maybe it is just that I need to spend a little bit more time to be more comfortable with Rust, and that will naturally guide me, as there might be conventions that I am not aware of?
Anton (Mar 02 2022 at 09:59):Some kind of guide that would explain at the high level the different pieces/modules in the code, and their responsibilities?
Excellent idea!
Anton (Mar 02 2022 at 10:02):I've made issue #2625 for this.
Anton (Mar 02 2022 at 10:06):Adding doc comments to every lib.rs file might be a good place to start. We could probable create a nice "reader-experience" from that with rustdoc.
Anton (Mar 02 2022 at 10:08):If others agree with this approach I can set up a checklist on github for every lib.rs file.
Brian Carroll (Mar 02 2022 at 12:01):Cool, this is good. A similar idea had occurred to me - putting readme markdown files into each crate directory. Not sure what the pros and cons are.
Brian Carroll (Mar 02 2022 at 12:02):I made a table of "starting points" in compiler/readme.md a while ago
Loric Brevet (Mar 02 2022 at 12:56):I am pleased with any idea that can help the overall understanding at the first glance, and both ideas seem valid to me! Then, it is maybe a matter of what is easier to maintain? Maybe it could help to stay close to what people do in the Rust community in terms of docs?
I still also think that having a file at the root of the repo named along the lines of ARCHITECTURE.md or TOUR_OF_CODEBASE.md with maybe simple diagrams or quick/high-level descriptions of modules could also help.
Last updated: Jun 16 2026 at 16:19 UTC