On team processes and policies
A pre-read for the "Team Processes and Policies" cross-team session at the Rust All Hands 2025
RustWeek 2025 is coming up and is host to the first Rust All Hands since Berlin 2019. There are a host of cross-team sessions being organised, including on “Team Processes and Policies” by myself. This post is a bit of a pre-read for attendees to elaborate on what I’d like to discuss!
There are other sessions at the All Hands focused on discussing what specific policies and processes ought to be, e.g. for the feature lifecycle (see Nadrieril’s session) or on specific collaboration between teams, but I’d like to focus on how we document those processes, coordinate on points where a process hands-off from one team to another, and how we present our contribution process in a clear and uniform way to users, etc.
There are also processes and policies which are related to the day-to-day running, organisation and structure of our teams, rather than our development processes, which could benefit from greater commonality between teams.
Rust’s teams have always been quite independent in deciding how they organise themselves and make decisions. That’s been a great benefit to the project as it has enabled teams to work in ways that suit them best and to adapt to the growth of the project quickly (e.g. more users, more features, more contributors, higher expectations, etc). However, this status quo isn’t without downsides:
If you’re a new contributor or an organisation looking to propose a change to Rust, then as soon as your contribution spans the remit of multiple teams and has multiple parts, things become less obvious: Do I need a RFC, ACP, MCP or multiple? Which team’s remit does this fall under? Do those teams’ documentation agree on how a proposal is received and accepted? etc.
Even for seasoned contributors, it isn’t obvious how other teams work and where to find that out: Is there documentation in the Rust Forge? On a team-specific website or repository? Or on a project-specific website or repository?
When a team changes its processes - such as when the compiler team introduced MCPs or the language team introduces “experiments” - there isn’t an established collaboration point where other teams can update their processes and policies to reflect that change.
As the Rust project grows, it makes sense for teams leads to coordinate and collaborate more on their processes and policies, and in that vein, there are three changes we could make that I think are worth discussing:
Centralised documentation
Cross-team policy coordination
Deduplicating policy and process
Centralised documentation
Suppose you’re brand new to the Rust project and want to contribute, or you’re interested in keeping up with a ongoing effort in the project, or you’re just curious about how a team works, where do you look? Maybe you start with the Rust website?
On the homepage, you can find a link titled “Read Contribution Guide” that takes you to the rustc-dev-guide, but that’s probably not exactly what you’re looking for - the rustc dev guide documents how the compiler works and how to build and test it, but not really how to propose a feature, or how to make a contribution, or how any given team is organised.
Maybe you try the “Governance” page on the website and find the link to the “RFC Process” which is where “each major decision in Rust starts”, that’s more helpful, and describes what an RFC is for - except that README hasn’t been updated for a few years, for example, neglecting to mention the language team’s processes for experiments. It helpfully links to processes for other teams, like the library team, as long as the process you’re looking for is from 2015 and doesn’t mention API Change Proposals.
Maybe you give up and just google it and stumble upon the Rust Forge, that’s got some helpful details: it has the up-to-date information for the compiler team; and some of the library team’s process, but not everything; and it’s silent on how to contribute a language feature or where you can find that process.
There’s no single place to find information about how the project works, how teams accept changes, how they collaborate, etc. From just a cursory search, there’s information split across all of these sources:
Information on platforms used by the project
Somewhat out-of-date, no teams are on the Rust Discord today
Documentation for triagebot
A stub for the defunct community team, linking to a repository that isn’t in the rust-lang organisation
All of the compiler team’s documentation, processes and policies
Crate removal and database maintenance procedures for crates.io
Some documentation on docs.rs
Charter of the leadership council and moderation team from the governance reform
Documentation on what project groups are
There’s no indication that we don’t really create project groups anymore, or mention of project goals which are nominally the successor of project groups
Project-wide policy on crate ownership
Most of the infrastructure team’s documentation
Out-of-date documentation for the language team
e.g. how to run a language team triage meeting on Discord and Zoom
Up-to-date but partial library team maintenance process
Almost all of the release team’s documentation
Documentation on how to manage an edition release
Archived content
compiler-team.rust-lang.org (previously)
We’ve recently moved all of our documentation to the Forge
Documentation on how to interact with the language team, become a member of the team, the principles behind the team’s decision making, how the team communicate, etc.
Documentation on the council’s processes/procedures (how to run elections, meeting observers, etc), committees, minutes, policies (spending, directorship, etc) and reports.
Documentation on team’s yearly planning process, meeting notes and a catalog of services maintained by the team and their details.
Meeting minutes, tools and collected data.
List of the team’s meetings and accepted FCPs.
Charter for triage working group.
Venue moderation policy, five year old list of Discord moderators, old team charter.
Team charter and policy for how the team establishes the canonical style for the language.
Minutes from meetings before 2023.
Many of these repositories also contain issues that teams use to track ongoing work, which is somewhat separate to the team’s documentation which would be useful to a contributor.
If you’re interested in the projects happening, of ambiguous and unclear status, if documented at all, that’s split over a dozen repos reflecting the terminology that was in fashion at the time:
And then if you want implementation documentation, there’s the developer guides:
..and that’s not including all of the repositories for teams and working groups that are entirely empty! If you’re interested in understanding and contributing to the project, it’s a mess of out-of-date and disparate resources, and that’s before considering whether team processes align: for example, if you have an approved language team experiment, it can’t link to the compiler team document for how to get started with your experiment, because we’ve never had that process; and if you’re interested in how to become a member of the project, you’ll find wildly different expectations depending on the team1.
It’s clear that the current state of the project’s documentation isn’t great for experienced contributors, nevermind new contributors, even when just ttrying to finding information, ignoring the gaps, out-of-date information and inconsistencies.
In the compiler team, we’ve been trying to consolidate our documentation into the Rust Forge and make sure that everything team members kept wishing was documented has been. For example, we recently documented the proposal mechanisms and approvals required for any given change under the compiler team’s remit:
It would be great for the project as a whole to consolidate our documentation in a few sources and start filling the gaps. I’d propose that we keep everything in one of two locations:
Rust Forge
The central source for documentation on how the project is structured, how teams work, what their remits are, how teams accept changes, how to join teams, etc - everything that isn’t implementation documentation.
This should include documentation on how to use all of the various tools we have - from triagebot to rustc-perf.
Developer Guides
We should keep our developer guides to document the implementations of the various components of the Rust toolchain (e.g. compiler, std, etc).
We should actively discourage the creation of one-off repositories to store documentation for projects or teams.
Cross-team Policy Coordination
A prospective contributor expects to propose a change to the Rust project, but in practice is proposing a change to one of the Rust teams and following that team’s process. As soon as a proposal involves another team’s remit, there’s often a entirely different process that needs to be followed. There are certainly commonalities, a simple patch is often just submitting a PR regardless of team, but as soon as you want to contribute anything more complex, there’s no single process to follow. If I want to propose a feature involving changes to the surface language, to Cargo, and to the standard library, what do I do need to write and how would I know that?
We should strive to establish a single “How to contribute to Rust?” workflow that links together the processes of each team and makes it straightforward to know whether you need to submit a patch, submit an MCP or write an RFC, and then which teams have to approve that and how they should approve that for any given change.
In the aforementioned “Proposals, approvals and stabilization” documentation in the compiler team, we have a handful of changes that just effectively just say “go work out what team X needs you to do” because there’s often nowhere appropriate to link to.
Whenever any team wants to change their processes, this should be proposed as a change to the project’s contribution workflow in our centralised documentation and require sign-off from team leads in the project. This acts as a coordination point to make sure that if the new process requires changes to how another team works then they can action that, or so that we can discover when teams are facing similar challenges which might prompt larger, more holistic changes to the entire project’s workflow.
Particularly as it relates to the feature lifecycle, it’s hard to define any team’s processes in isolation - the language team accept RFCs which are implemented by the compiler team and can lead to revisions to the accepted design, which can lead to more implementation and so on. We could change the artefacts we collect to reflect this reality - imagine that a proposed feature wasn’t a single RFC document but rather a directory, containing an initial problem statement and motivation document, a proposed solution document, potentially alternative solution documents, then any number of design revision documents following implementation and finally the stabilisation report for the feature.
Deduplicating policy and process
Its not uncommon for policies adopted by one team to trickle down to other teams over time - the compiler team introduced a contributor role in 2019, the library team in 2021 and clippy team introduced theirs in 2024. The compiler team have since adopted a new, more relaxed membership process and team/maintainer distinction and I’ve been asked by library team leads about whether it makes sense to adopt a similar structure and even merge parts of the non-maintainer teams.
In the past, I’ve written about how the idea of “general project membership” might make sense for the Rust project, and so unifying and coordinating on our team membership expectations and policies might make sense and reduce duplicated effort across teams, especially when everything is documented in a single place and we’re used to evolving these policies collaboratively.
Unified processes and policies makes it easier to understand how the Rust project works and contribute to it, and are much less restricting when there’s an established process for how teams can propose changes to the processes and policies and collaborate to agree on the details.
As another example, the compiler team’s major change proposals process could be generalised to become a project-wide major change proposal, used for decisions that don’t quite warrant full and heavyweight RFCs, or non-user-facing decisions. This could be used for the library team’s API Change Proposal (ACP), and simplify the distinct kinds of proposals we ask contributors to make.
These are all just some vague ideas to kickstart some conversation in the cross-team session on how we can improve the way that Rust’s project teams define and collaborate on our processes and policies. See you at the session!
Different expectations for different teams make sense sometimes - the moderation and infrastructure teams aren’t like the rest of the project, for example, and it makes sense to have fewer people in the language team than the compiler team, but implementation-focused teams could have much more similar expectations.