Ask questionsMake `CONTRIBUTING.md` into a series of tutorials
CONTRIBUTING.md to contain explicit instructions (as in a series of shell commands) for a variety of common tasks for new contributors. For example, "modifying the standard library documentation", "adding a function to the standard library", "modifying
rustc itself", or "modifying a submodule". Move all information that is unlikely to be needed by newer contributors (e.g., "Creating a new subtree dependency", "updating submodules") to the dev-guide or the Forge.
The basic idea is to make the target audience of
CONTRIBUTING.md exclusively newer contributors, while documenting the details in the dev-guide. The goal here is to avoid overwhelming new people by explaining, step-by-step, how to perform specific tasks without needing a detailed understanding of the build system or bootstrapping process.
Right now, Chapter 1 of the dev-guide contains pretty much everything you need to know, but goes into great detail in some sections, meaning that people have to read through a lot of text in order to figure out how to perform a small task. I suspect that people who, for example, simply want to edit and build the documentation for
std locally will not make it through the whole thing. My hope is, by making step-by-step instructions the first thing new contributors see, we can lower the barrier to entry.
This is a major change proposal, which means a proposal to make a notable change to the compiler -- one that either alters the architecture of some component, affects a lot of people, or makes a small but noticeable public change (e.g., adding a compiler flag). You can read more about the MCP process on https://forge.rust-lang.org/.
This issue is not meant to be used for technical discussion. There is a Zulip stream for that. Use this issue to leave procedural comments, such as volunteering to review, indicating that you second the proposal (or third, etc), or raising a concern that you would like to be addressed.
#t-compiler/major changeswill be created for this issue.
@rustbot secondcommand. This should only be done by someone knowledgable with the area -- before seconding, it may be a good idea to cc other stakeholders as well and get their opinion.
major-change-acceptedlabel is added and the issue is closed. You can link to it for future reference.
A note on stability. If your change is proposing a new stable feature, such as a
-C flag, then a full team checkoff will be required before the feature can be landed. Often it is better to start with an unstable flag, like a
-Z flag, and then move to stabilize as a secondary step.
Answer questions ecstatic-morse
I checked with steveklabnik, who said that
CONTRIBUTING.md is now under the purview of the compiler team since the docs team is no more. For the record, I would also be happy if the "tutorials" became the first chapter of the dev-guide and
CONTRIBUTING.md simply linked to each chapter. I simply want one authoritative source.
cc @rust-lang/wg-rustc-dev-guide since this will involve adapting the relevant parts of the first chapter into the "tutorial" framework.
FWIW, Ruby on Rails does a decent job of this in my opinion, although it's in their book and not in the main repo.
Related questionsNo questions were found.