Rustc Reading Club DRAFT RFC

Here’s a spoiler for Monday’s discussion on RRC Phase II. You’ll still want to join us on Monday for the Muppets. Everything is better with Muppets. We will be seeking feedback and discussion on this RFC following the CTCFT presentation.

Cohorts Rock

• Feature Name: rustc_reading_club_phase_ii
• Start Date: 2022–03–31
• RFC PR: N/A (yet)
• Rust Issue: N/A (yet)

Summary

The Rustc Reading Club has two goals. First, to produce confident new contributors to rustc. Second, to deepen understanding of rustc for mid level contributors. The structure of RRC enables participants to gain experience working with other contributors making their future collaborations easier.

Phase I of the Rustc Reading Club is complete and now we are ready to launch Phase II based on what we’ve learned. Phase I focused solely on rustc’s name resolver module. We plan to expand and “read” other areas of the compiler in Phase II.

Motivation

Recruiting Tool for New Contributors to Rustc

Code reading clubs provide a set of exercises that with repetition empower participants to reason about the code they read and to read code faster. We are interested in applying this technique to becoming a contributor to the rust compiler. RRC isn’t intended or designed to be the only method used in a Rust Contributor Program but it is our belief that code reading can be a tool for many Rust teams and their efforts to on board new and experienced contributors. Based upon our experience in the pilot or Phase I of RRC, the guided discussion of unfamiliar sections of rustc in a group setting improved understanding of the source code for the participants. Reading clubs, in general, work by completing multiple iternations of reading and reasoning about code which results in learning to read code faster and being able to reason about it on one’s own.

A key finding from RRC Phase I was that mixing rustc contributor aspirants with more experienced and knowledgable mid level rust developers didn’t work. The observations and higher level discussion of the source code were difficult to engage in for those new to contributing to the rust project.

The RustcContributor::new program in Phase II is planned to run twice each year in the Spring and Fall with the objective of taking aspirants from Zero to First PR.

Deepening Knowledge of Existing Contributors On a Specific Module/Area

The characteristics of those who wanted to participate in the RRC fell into two groups. There were existing compiler contributors who wanted to gain more knowledge and understanding of a specific area of the compiler. The other group were rust developers with experience writing rust in other domains like Gamedev, blockchain or job-related tasks outside the rust org.

Phase I produced two participants at this level who were ready and eager to become compiler contributors for the name resolver. They still needed mentorship to prioritize the right next steps. Phase I didn’t include a process to onboard them to deliver commits to the name resolver and this is a gap that Phase II plans to fill.

Guide-level explanation

RustcContributor::new Program

The program will run twice per year for two months once in the Spring and then again in the Fall. New contributors will have an additional month to complete on boarding and then join a RustcContributor::grow cohort which is the second month of the program. The selection process needs more discussion and input from the complier team and working groups. A starting point for the discussion for the first month would look like the following.

Before the program starts:

• teams/leaders or wgs will gather a list of suitable bugs
• take applications for a month
• assemble an initial cohort list

Week 1: Onboarding

• how to use your cloud desktop and get rustc running
• introduce rustc-dev-guide
• introduce rustc module/area
• attend office hours when needed

Week 2: Fix Bugs with Logs

• we’ll introduce a trivial bug
• use logs to track it down
• attend office hours when needed
• each applicant emails a summary

Week 3: Fix Week 3 Bug with Pernos.co

• same process as week 3 but use pernos.co instead of logs
• attend office hours when needed
• each applicant emails a summary

Week 4: Bug Fix on your own

• each applicant has a bug and section of the rustc dev guide assigned to them
• provide a target time to fix (some N hours)
• attend office hours when needed
• each applicant emails a summary of their bug fix

Post Program

• join a RustcContributor::grow cohort.

RustcContributor::grow Program

The program will run on a cadence of every 8 weeks with sessions of 90 minutes each and last for 4 weeks. This part of the program is interactive and requires attendance by participants. It begins with and opening lecture and has the following structure.

Week 1: Opening lecture

• statement of skill level required for successful participation
• recorded lecture on the module/are
• cursory reading of the source code
• read examples if they exist
• discuss things in the code that seem interesting (for whatever reasons)

Week 2: Code Example 1

• discuss what makes the example interesting
• pause interaction to let people read example individually to get familiar with the code and make notes of questions and observations to share with the group
• have people explore trace to answer those questions with instructor’s guidance

Week 3: Code Example 2

• discuss what makes the example interesting
• pause interaction to let people read example individually to get familiar with the code and make notes of questions and observations to share with the group
• have people explore trace to answer those questions with instructor’s guidance

Week 4: Code Example 3

• discuss what makes the example interesting
• pause interaction to let people read example individually to get familiar with the code and make notes of questions and observations to share with the group
• have people explore trace to answer those questions with instructor’s guidance

Post Program

• assign mentor(s) to the group of people interested in where to make their first meaningful bug fix or other contribution to the module/area covered.

Reference-level explanation

Support for RustcContributor::new and RustcContributor::grow will require support from rust-lang org and possibly the Rust Foundation. The specific needs include:

• Application reviewers for the RustcContributor::new cohort
• Program Managers ( 1to 2)
• Mentors for office hours (3 to 4)
• Reviewer(s) for email submissions of bug fixes
• Instructors (5 to 6)
• Each participant will be provided with a cloud desktop and a license for pernos.co
• Mentors to guide cohorts and participants to team membership or being a committer
• A dedicated public Zulip stream for each cohort
• Instructors recognized with “Certified Rust Instructor” badges.

Rationale

Build a Pipeline of Rust Contributors

The benefits onboarding new contributors is likely obvious to current maintainers and contributors. There’s much work to be done and as Rust continues it meteoric adoption demands for bug fixes, new features and increased stability with grow. In addition, new people bring new ideas along with fresh prespectives and experiences.

These programs allow Rust to onboard groups of people at a regular cadence. Of course, not all of them will stay for long periods but this is the purpose of establishing cohorts on a rolling basis.

Prevent Over Commitment by Instructors

Constraining the programs cohorts to one and two month durations ensures that instructors don’t burn out as they can choose their schedules without concerns of volunteering for a never ending commitment.

Prior art

The Code Reading Club

The Code Reading Club is an experiment to build the skill of reading unfamiliar code both phonetically and analytically through a series of exercises.

Rustc Reading Club Phase I

The Rustc Reading Club has been an experiment to build on the foundations of code reading to learn rustc source code and onboard new contributors.

Unresolved questions

This is beginning of a discussion with the compiler team and others in rust-lang that need to onboard new contributors. Your feedback is critical to make these programs work.

You can help by either attending the April, 18 2022 CTCFT or watching the recording and then adding your thoughts to this RFC.

Future possibilities

The goals of RustcContributor::new and RustcContributor::grow can be adopted and adjusted by other teams and working groups in the rust-lang org to suit their needs and processes. With the support of teams and working groups we will succeed in building a healthy pipeline of contributors and provide maintainers with the knowledgable support they need to continue delivering the most loved language by developers according to Stack OverFlow. :)