Migrate CONTRIBUTING.md to an mdbook

We had a suggestion that the dev docs would be easier to read if there
was a table of contents. Rather than making one by hand I thought using
mdbook would be better.

Author: rbtcollins

.github/workflows/deploy-docs.yaml

@@ -6,8 +6,11 @@ on:
       - stable
       - master
 
-# Builds docs for both stable and master branches.
-# stable is placed in the root of the gh-pages branch, while master is placed at /devel
+# Builds all docs for both stable and master branches.
+# In the gh-pages branch, we place:
+# stable user-guide at /
+# master user-guide at /devel
+# master dev-guide at /dev-guide
 
 jobs:
   doc:
@@ -36,6 +39,10 @@ jobs:
           cd doc/user-guide
           mdbook build
           mv book ${{ runner.temp }}/book/devel
+          # Build dev-guide for master
+          cd ../dev-guide
+          mdbook build
+          mv book ${{ runner.temp }}/book/dev-guide
       - name: Deploy to GitHub
         run: |
           cd ${{ runner.temp }}/book

.github/workflows/test-docs.yaml

@@ -21,7 +21,11 @@ jobs:
           mkdir mdbook
           curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.6/mdbook-v0.4.6-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
           echo "`pwd`/mdbook" >> $GITHUB_PATH
-      - name: Build book
+      - name: Build user-guide
         run: |
           cd doc/user-guide
+          mdbook build
+      - name: Build dev-guide
+        run: |
+          cd doc/dev-guide
           mdbook build

CONTRIBUTING.md

@@ -21,7 +21,7 @@ documentation on installing and using Rustup.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for information on contributing to Rustup.
+See [**The Rustup dev guide**](https://rust-lang.github.io/rustup/dev-guide) for information on contributing to Rustup.
 
 ## License
 

README.md

@@ -0,0 +1 @@
+book

doc/dev-guide/.gitignore

@@ -0,0 +1,28 @@
+# rustup documentation
+
+This directory contains rustup's developer / contributing documentation.
+
+## Building the book
+
+Building the book requires [mdBook](https://github.com/rust-lang/mdBook). To get it:
+
+```console
+$ cargo install mdbook
+```
+
+To build the book:
+
+```console
+$ mdbook build
+```
+
+`mdbook` provides a variety of different commands and options to help you work
+on the book:
+
+* `mdbook build --open`: Build the book and open it in a web browser.
+* `mdbook serve`: Launches a web server on localhost. It also automatically
+  rebuilds the book whenever any file changes and automatically reloads your
+  web browser.
+
+The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and
+every file must be linked there.

doc/dev-guide/README.md

@@ -0,0 +1,11 @@
+[book]
+authors = ["The Rust Project Developers"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Rustup developer guide"
+
+[output.html]
+edit-url-template = "https://github.com/rust-lang/rustup/edit/master/doc/dev-guide/{path}"
+git-repository-url = "https://github.com/rust-lang/rustup/tree/master/doc/dev-guide"
+site-url = "https://rust-lang.github.io/rustup/dev-guide"

doc/dev-guide/book.toml

@@ -0,0 +1,8 @@
+# Summary
+
+- [Introduction](index.md)
+- [Coding standards](coding-standards.md)
+- [Version numbers](version-numbers.md)
+- [Release process](release-process.md)
+- [Tips and tricks](tips-and-tricks.md)
+- [Tracing](tracing.md)

doc/dev-guide/src/SUMMARY.md

@@ -0,0 +1,64 @@
+
+# Coding standards
+
+Generally we just follow good sensible Rust practices, clippy and so forth.
+However there are some practices we've agreed on that are not machine-enforced;
+meeting those requirements in a PR will make it easier to merge.
+
+## Import grouping
+
+In each file the imports should be grouped into at most 4 groups in the
+following order:
+
+1. stdlib
+2. non-repository local crates
+3. repository local other crates
+4. this crate
+
+Separate each group with a blank line, and rustfmt will sort into a canonical
+order. Any file that is not grouped like this can be rearranged whenever the
+file is touched - we're not precious about having it done in a separate commit,
+though that is helpful.
+
+## No direct use of process state outside rustup::currentprocess
+
+The `rustup::currentprocess` module abstracts the global state that is
+`std::env::args`, `std::env::vars`, `std::io::std*`, `std::process::id`,
+`std::env::current_dir` and `std::process::exit` permitting threaded tests of
+the CLI logic; use `process()` rather than those APIs directly.
+
+## Clippy lints
+
+We do not enforce lint status in the checks done by GitHub Actions, because
+clippy is a moving target that can make it hard to merge for little benefit.
+
+We do ask that contributors keep the clippy status clean themselves.
+
+Minimally, run `cargo +beta clippy --all --all-targets -- -D warnings` before
+submitting code.
+
+If possible, adding `--all-features` to the command is useful, but will require
+additional dependencies like `libcurl-dev`.
+
+Regular contributors or contributors to particularly OS-specific code should
+also make sure that their clippy checking is done on at least Linux and Windows,
+as OS-conditional code is a common source of unused imports and other small
+lints, which can build up over time.
+
+For developers using BSD/Linux/Mac OS, there are Windows VM's suitable for such
+development tasks for use with virtualbox and other hypervisors are downloadable
+from
+[Microsoft](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/).
+Similarly, there are many Linux and Unix operating systems images available for
+developers whose usual operating system is Windows. Currently Rustup has no Mac
+OS specific code, so there should be no need to worry about Mac VM images.
+
+Clippy is also run in GitHub Actions, in the `General Checks / Checks` build
+task, but not currently run per-platform, which means there is no way to find
+out the status of clippy per platform without running it on that platform as a
+developer.
+
+### import rustup-macros::{integration,unit}_test into test modules
+
+These test helpers add pre-and-post logic to tests to enable the use of tracing
+inside tests, which can be helpful for tracking down behaviours in larger tests.

doc/dev-guide/src/coding-standards.md

@@ -0,0 +1,41 @@
+# Contributing to rustup
+
+1. Fork it!
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Test it: `cargo test --features=test`
+4. Lint it: `cargo +beta clippy --all --all-targets -- -D warnings`
+
+> We use `cargo clippy` to ensure high-quality code and to enforce a set of best practices for Rust programming. However, not all lints provided by `cargo clippy` are relevant or applicable to our project.
+> We may choose to ignore some lints if they are unstable, experimental, or specific to our project.
+> If you are unsure about a lint, please ask us in the [rustup Discord channel](https://discord.com/channels/442252698964721669/463480252723888159).
+
+5. Commit your changes: `git commit -am 'Add some feature'`
+6. Push to the branch: `git push origin my-new-feature`
+7. Submit a pull request :D
+
+For developing on `rustup` itself, you may want to install into a temporary
+directory, with a series of commands similar to this:
+
+```bash
+cargo build
+mkdir home
+RUSTUP_HOME=home CARGO_HOME=home target/debug/rustup-init --no-modify-path -y
+```
+
+You can then try out `rustup` with your changes by running `home/bin/rustup`, without
+affecting any existing installation. Remember to keep those two environment variables
+set when running your compiled `rustup-init` or the toolchains it installs, but _unset_
+when rebuilding `rustup` itself.
+
+If you wish to install your new build to try out longer term in your home directory
+then you can run `cargo dev-install` which is an alias in `.cargo/config` which
+runs `cargo run -- --no-modify-path -y` to install your build into your homedir.
+
+We use `rustfmt` to keep our codebase consistently formatted. Please ensure that
+you have correctly formatted your code (most editors will do this automatically
+when saving) or it may not pass the CI tests.
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the
+Apache-2.0 license, shall be dual licensed as in the README, without any
+additional terms or conditions.