Make CONTRIBUTING.md into a series of tutorials

[ecstatic-morse]

TL;DR

Rewrite 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.

Links and Details

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.

Mentors or Reviewers

???

What is this issue?

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.

MCP Checklist

• MCP filed. Automatically, as a result of filing this issue:
  • The @rust-lang/wg-prioritization group will add this to the triage meeting agenda so folks see it.
  • A Zulip topic in the stream #t-compiler/major changes will be created for this issue.
• MCP seconded. The MCP is "seconded" when a compiler team member or contributor issues the @rustbot second command. 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.
• Final comment period (FCP). Once the MCP is approved, the FCP begins and lasts for 10 days. This is a time for other members to review and raise concerns -- concerns that should block acceptance should be noted as comments on the thread, ideally with a link to Zulip for further discussion.
• MCP Accepted. At the end of the FCP, a compiler team lead will review the comments and discussion and decide whether to accept the MCP.
  • At this point, the major-change-accepted label 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.

[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.

[mark-i-m]

Yep, I do think we should move much of that content either to the first chapter of the guide or to forge (there is some ongoing discussion about organization of the guide)...

[spastorino]

We are in the process of thinking about the structure of the Rustc Dev Guide. I want to have something like a Getting started first section in the guide that is more or less what you're describing without the details, the details should be left for specific chapters. I wonder if it's worth having both that and a bunch of CONTRIBUTING.md files. One possibility is also getting rid of CONTRIBUTING.md files or pointing from those to the guide and have everything in the guide.

[spastorino]

@rustbot second