We’ve been running an experiment of reading rustc code for the past four months to learn how we can use the model of code reading combined with cohorts to encourage new contributors to rustc and to strengthen understanding of a specific section of the compiler, namely the name resolver, for experienced rust developers. As this phase of the project came to a close, we decided to do a retrospective and the insights we gained from the process along with our own observations will bring major changes to the next phase of the Rustc Reading Club (RRC). First, let’s take a look at what we found from the retrospective.
Background
Niko Matsaskis led all of the sessions and did several experiments with the session flow. Over time our approach became more targeted. Initially we tried following the more comprehensive methods of our namesake, The Code Reading Club (CRC). While the CRC method is ideal for gaining experience with unknown code, we found that it wasn’t well suited for our goal of understanding the specific rustc name resolver source code.
General Findings
- Mixing experience levels didn’t really work as we had hoped it would. Part of the benefit of doing an exercise like code reading is that it doesn’t require much pre work. Or least that’s what we thought at the beginning. If all the “work” could be done inside a 90 minute session then people would be more likely to participate and not fall behind. These assumptions proved incorrect in more than one situation. First, the leader of the session needs to select a section of code to focus the session. Next, if you are not experienced with Rust development reading the documentation is something you would normally do as part of your learning process. That need doesn’t disappear just because you are working as part of a group, and sadly, we don’t yet have the ability to “jack into” the matrix and learn Kung Fu or Rust.
- Having an undefined number of sessions for RRC is problematic. We had many questions when we began this experiment. One of them was, How many sessions will it take to cover the name resolver? We had never done this before so no one knew the answer. Setting up the club without a defined timeline left the leader and the cohort uncertain of what they could expect to cover in a single session and unclear on the commitment required of them.
- Pernosco is helpful when investigating unfamiliar source code. Pernosco is a debugging tool, but we used it to observe and navigate through various instances of execution of different sections of the name resolver. We used its tools to investigate what happens when a given function is executed. Observing what is on the call stack. Displaying what calls are made. Viewing what variables are available and so on. Learning Pernosco has a heavy lift for many of us. There is a video of a presentation by Felix Klock on Pernosco during one RRC session. It would be helpful to have a future presentation on Pernosco that focuses on the RRC use case.
- Need a defined process to help RRC members land that first PR. Phase I produced two new contributors to the name resolver. Others expressed an interest in continuing the journey of becoming contributors to rustc with more experience through the RRC along with gaining more knowledge and experience with rust and the tools used. There is still a gap between being an RRC participant and becomng a confident contributor. Existing rustc mentorship may be a solution, but more feedback from the compiler team is needed to solve this.
- Getting a review of the source code from an expert added insights. The final session of Phase I was a tour of the name resolver led by Vadim Petrochenkov. Most rustc crates have an expert or the most knowledgeable maintainer or contributor to that particular module. For the name resolver that person is Vadim Petrochenkov. The content generated from this session was recorded and likely will be helpful to the rust community beyond just the RRC. After our struggles to understand the name resolver this review generated some new understanding, excellent questions and possible ideas for future development.
Retrospective Responses
What Worked
- As someone who hasn’t contributed to the compiler, it was nice to meet people who do work on the compiler, and what parts of the codebase look like.
- Getting to know each other through regular meetings of a small group means we feel comfortable reaching out to each other outside the sessions.
- Introducing the code before the session. This could also be valuable to the community on the whole as a recorded description/explanation.
What Didn’t Work
- Consistent attendance?
- Overviews that are too zoomed out.
- Finding a level in the content that was interesting to those working with the compiler, working in other areas of rust and aspirants.
- More people elected to not attend when the video recording was announced.
What can be improved
- How parts of the club are recorded for others to watch.
- How to galvanize the large amount of interest in this club.
- Tooling that is used?
- Pronosco?
- What other tools might help at a mid level?
- Helpful to walk through stack trace
- Inspecting with some kind of debugger that isn’t as complex
— GDB?
— rr? - Ways to see the process of actually contributing
— https://rust-lang.zulipchat.com/#narrow/stream/305296-rustc-reading-club/topic/Call.20for.20action/near/269598039 ←per discussion this isn’t a reading club - Reading club focused on the dev guide or other resources
— Helps prevent people coming in and only knowing what is shown at the meetings. - Perhaps open with asking everyone what they hope to get from the session and explain the prupose of the RRC.
- …wanted to see more speakers like the Pernosco demo and the Petrochenkov talk.
- I’m ambivelant on this point as we don’t want to become a meetup.
- Maybe only record Niko’s introduction or description of a topic versus the whole session. It might generate more interest.
Next Steps
We have begun the steps to plan for Phase II which will include changes in response to what we learned in Phase I. I’m really excited about this next better phase and widening participation from more members of the rust community. There are also other Reading Club experiments like the ARC (Async Reading Club) that functions differently from the RRC. Once the details of the next phase have been agreed to by the compiler team updates and the new plan will be posted here. Stay tuned. Great things are coming!
