Make contributing.md into a series of tutorials

[mark-i-m]

as per rust-lang/compiler-team#296

cc @ecstatic-morse

We probably also want to figure out how to integrate relevant existing walkthrough sections (e.g. https://rustc-dev-guide.rust-lang.org/walkthrough.html) and planned ones.

[ecstatic-morse]

Thanks for getting this moving with rust-lang/compiler-team#320! I would like to see the first two chapters reorganized so that they follow the typical order of a contribution to rustc. The following was what I had in mind:

• Initial setup

  • System requirements
  • Cloning and building
  • config.toml
    • incremental = true
    • debug-assertions = true
  • Add ./x.py fmt --check to git hooks
  • Beware long initial build time
    • ./x.py check

• Typical in-tree contributions

  • Licensing/coding conventions
  • Improving the documentation
    • ./x.py doc --stage 0 src/libstd
  • Implementing a new feature
    - MCP vs. RFC
    - Opening a Tracking Issue
  • Modifying the standard library
    • Stability attributes / logistics
    • ./x.py build --stage 0 src/libstd
    • ./x.py test --stage 0 src/libstd to run unit tests
    • --keep-stage
  • Modifying the compiler
    • Custom toolchains
    • ./x.py build --stage 1 src/libstd
    • Reminder about keep-stage
    • Writing UI tests
      • ./x.py test --stage 1 -- src/test/ui to run UI tests
    • Adding crates.io dependencies
  • Modifying submodules
    • ???

• Opening a PR

  • squashing and rebasing
  • bors
  • FCP

• Troubleshooting

  • How to ask for help
  • Backtraces and logging
  • rustc in a debugger (and why this will be very slow)
  • Profiling the compiler

The basic idea is that you could follow along section-by-section, picking the "typical in-tree contribution" that you are interested in. Things that don't fit into this framework like "Errors and Lints" would be moved to a later chapter. I'd also like to have an "Out-of-tree contributions" chapter, although I'm not sure if the rustc-dev-guide is the right place. Maybe that should live in CONTRIBUTING.md?

[mark-i-m]

@rust-lang/wg-rustc-dev-guide was actually planning to focus on guide organize this sprint. @spastorino also had thoughts about this.

One major question is how much stuff should go in the guide vs the forge.

I do like the idea of organizing the chapters in order of what someone might need.

[ecstatic-morse]

My impression of the guide/forge split is that the forge is specifically targeted at org members while the guide is targeted at everyone who wants to contribute. I envisioned that sections like "licensing" and "bors" would contain only the minimum amount of information needed by new contributors.

[mark-i-m]

My impression of the guide/forge split is that the forge is specifically targeted at org members while the guide is targeted at everyone who wants to contribute.

@ecstatic-morse This was my original intention for the rustc-dev-guide too. However, @nikomatsakis and @spastorino were looking to move to a model where the guide only contains information about how the compiler works, and other more procedure-related documentation would go to the forge. The thought was that the guide is getting rather long, and moving stuff to the forge would help make it less overwhelming. Personally, I still like the idea of the guide being a 1-stop shop for contributors....

[nikomatsakis]

It's true, I've been advocating for documentation of procedures and things to move to forge, with rustc-dev-guide more focused on "how the code works", but I think that having some minimal coverage of bors and so forth would be ok, perhaps with the details over at forge.

Still, I don't quite agree with @ecstatic-morse's version that forge is mostly of interest to "org members". I imagine that forge would be a good place to go and learn about MCPs, for example, and that seems a bit out of scope to me for rustc-dev-guide. But I do think it's reasonable that you could find everything you need to make a "small contribution" in the rustc-dev-guide.

[spastorino]

Exactly what @nikomatsakis have said. The model I like is something like what was suggested ... "the guide only contains information about how the compiler works, and other more procedure-related documentation would go to the forge" but including also what Niko have said ... with some minimal coverage of other stuff that lives in forge that we could link for further details.

[follower]

[FWIW some feedback from someone who is (again :) ) attempting to learn Rust, encountered a small typo in standard lib docs & wanted to contribute a fix (https://github.com/rust-lang/rust/pull/77050).]

It seems the recent decision/changes to use the rustc-dev-guide as the canonical source for information on how to contribute the Rust project as a whole has led to a situation where initial contributor experience is IMO less welcoming & document descriptions are no longer accurate.

A potential contributor's journey

e.g. currently, as a first time contributor, as of 1.46.0 I:

1. Go to https://doc.rust-lang.org/std/index.html#contributing-changes-to-the-documentation.
2. Follow link to https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md and then to https://rustc-dev-guide.rust-lang.org/getting-started.html (Nightly now links to the latter directly: https://doc.rust-lang.org/nightly/std/index.html#contributing-changes-to-the-documentation.)
3. Suddenly see a lot of text about building the compiler...causing me to panic(). :D

or, I:

1. Go to https://github.com/rust-lang/rust (i.e. https://github.com/rust-lang/rust/blob/master/README.md) and follow link to...
2. ... https://rustc-dev-guide.rust-lang.org/getting-started.html
3. And... panic().

This is in contrast to the (apparently previous) experience changed by rust-lang/rust@3f6928f#diff-6a3371457528722a734f3c51d9238c13L1 which would instead lead to a CONTRIBUTING.md (content now present in https://rustc-dev-guide.rust-lang.org/contributing.html) which starts with a helpful Table of Contents with links to specific types of contributions I might want to be making. (And, IMO more likely to be first contributions.)

Descriptions of rustc-dev-guide purpose

In addition, About this guide describes its purpose as:

This guide is meant to help document how rustc – the Rust compiler – works, as well as to help new contributors get involved in rustc development.

And https://github.com/rust-lang/rustc-dev-guide/blob/master/README.md describes the purpose as:

...a collaborative effort to build a guide that explains how rustc works. The aim of the guide is to help new contributors get oriented to rustc, as well as to help more experienced folks in figuring out some new part of the compiler that they haven't worked on before.

Neither of which seems to make me feel I'm in the right place to e.g. simply make a documentation change. (At this point I don't even know that e.g. standard library documentation is extracted from the library source files.)

The cause of the confusion?

So, to me, it seems like the intention is that rustc-dev-guide is now the "Rust Dev Guide" but the content/arrangement of the guide doesn't currently reflect that.

I currently have a related PR rust-lang/rust#77195 to change the standard library to link to the documentation-specific part of the contributing section but thought I'd mention the wider issue here as that's not the only place affected by the change in focus.