Now that the trains are running, and subteams have been established as a thing, we can make some desperately need changes to The Process of making changes to APIs.
I posit the following premises:
- The amount of concensus building and process a change requires should be proportional to controversy, importance, and size of a change. Hard things should be hard; Easy things should be easy.
- RFCs are heavyweight
- PRs are lightweight
- RFCs are only useful if a significant and diverse portion of the community actively consumes and discusses them
- The more RFCs there are – particularly trivial ones – the less likely people are to interact with them. This may be due to exhaustion, being overwhelmed, being too busy, or being unable to effectively identify the RFCs that concern them. This is particularly important because professionals and domain experts are exactly the people we want chiming in, but also have the least time. We are surely lost if the only people who can deal with RFCs are hobbyists with all the time in the world.
As a result, I propose the following Life and Death of an API:
- Someone wants to make a change:
- The change is sweeping, or an entire new module/crate/major-API: Submit an RFC
- The change is to something unstable, or just adding a method: Submit a PR
- Not sure: Submit a PR (particularly more friendly for new contributors, or those that are uncomfortable with RFCs)
- Someone reviews a PR, after normal discussion:
- If it’s clearly not acceptable: Close the PR
- If it’s clearly useful or filling a hole: Merge as Unstable
- If it’s not clear: Ping the larger team for input
- If concensus still can’t be reached: Block on an RFC
- If a change makes it through the whole RFC process: Merge as Unstable
- An unstable API has been around for at least one full release cycle, the team should discuss it:
- If demand is high for stabilization, or the API otherwise seems to be pulling its weight: Mark as stable in the next beta
- If an API isn’t pulling its weight: deprecate for removal in next release (giving an opportunity for community objections)
- regardless of the action taken here: announce this transition in weekly team notes (maybe also some release notes?). The community should be aware of this, and able to provide feedback!
- Deprecations of stable APIs requires an RFC
- Due to the way that trait implementations effectively bypass the Trains, they may always require an RFC, except for perhaps the most trivial cases (like missing Debug or Clone impls)
The main point is: everyone should favour PRs, with RFCs reached for only for major changes or for achieving concensus where the team can’t. However the community should be able to interact with and track the process at all levels. The team’s responsibility should be on keeping changes flowing freely and seek broader community input only when necessary/ready. The larger community shouldn’t be bothered with day-to-day development.