Auto merge of #11869 - epage:impl, r=weihanglo

docs(contrib): Pull impl info out of architecture

This is a follow up to #11809.

Personally, I found mixing this stuff with architecture less than ideal as it buried the more practical information among details that might not have been as important.  With us moving architecture information into doc comments, this provides us an opportunity to rectify this.

Not a fan of the name of this chapter but its a start.

I've left in the old architecture chapter as there is still content to find a home for (resolver).

Author: bors

src/doc/contrib/src/SUMMARY.md

@@ -7,10 +7,14 @@
     - [Release process](./process/release.md)
     - [Unstable features](./process/unstable.md)
 - [Design Principles](./design.md)
+- [Implementing a Change](./implementation/index.md)
+    - [Architecture](./implementation/architecture.md)
+    - [New subcommands](./implementation/subcommands.md)
+    - [Console Output](./implementation/console.md)
+    - [Filesystem](./implementation/filesystem.md)
+    - [Debugging](./implementation/debugging.md)
 - [Architecture](./architecture/index.md)
     - [Codebase Overview](./architecture/codebase.md)
-    - [SubCommands](./architecture/subcommands.md)
-    - [Console Output](./architecture/console.md)
     - [Packages and Resolution](./architecture/packages.md)
     - [Compilation](./architecture/compilation.md)
     - [Files](./architecture/files.md)

src/doc/contrib/src/architecture/files.md

@@ -1,25 +1,3 @@
 # Files
 
 See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html)
-
-## Filesystems
-
-Cargo tends to get run on a very wide array of file systems. Different file
-systems can have a wide range of capabilities, and Cargo should strive to do
-its best to handle them. Some examples of issues to deal with:
-
-* Not all file systems support locking. Cargo tries to detect if locking is
-  supported, and if not, will ignore lock errors. This isn't ideal, but it is
-  difficult to deal with.
-* The [`fs::canonicalize`] function doesn't work on all file systems
-  (particularly some Windows file systems). If that function is used, there
-  should be a fallback if it fails. This function will also return `\\?\`
-  style paths on Windows, which can have some issues (such as some tools not
-  supporting them, or having issues with relative paths).
-* Timestamps can be unreliable. The [`fingerprint`] module has a deeper
-  discussion of this. One example is that Docker cache layers will erase the
-  fractional part of the time stamp.
-* Symlinks are not always supported, particularly on Windows.
-
-[`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs
-[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html

src/doc/contrib/src/architecture/filesystem.md

@@ -0,0 +1 @@
+# Filesystem

src/doc/contrib/src/implementation/architecture.md

@@ -0,0 +1,5 @@
+# Architecture Overview
+
+See the
+[nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html)
+for an overview of `cargo`s architecture and links out to further details.

src/doc/contrib/src/architecture/console.md renamed to src/doc/contrib/src/implementation/console.md

@@ -55,28 +55,4 @@ Some guidelines for Cargo's output:
   and use multiple sentences. This should probably be improved sometime in the
   future to be more structured.
 
-## Debug logging
-
-Cargo uses the [`env_logger`] crate to display debug log messages. The
-`CARGO_LOG` environment variable can be set to enable debug logging, with a
-value such as `trace`, `debug`, or `warn`. It also supports filtering for
-specific modules. Feel free to use the standard [`log`] macros to help with
-diagnosing problems.
-
-```sh
-# Outputs all logs with levels debug and higher
-CARGO_LOG=debug cargo generate-lockfile
-
-# Don't forget that you can filter by module as well
-CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile
-
-# This will print lots of info about the download process. `trace` prints even more.
-CARGO_HTTP_DEBUG=true CARGO_LOG=cargo::ops::registry=debug cargo fetch
-
-# This is an important command for diagnosing fingerprint issues.
-CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build
-```
-
-[`env_logger`]: https://docs.rs/env_logger
-[`log`]: https://docs.rs/log
 [`anyhow`]: https://docs.rs/anyhow

src/doc/contrib/src/implementation/debugging.md

@@ -0,0 +1,26 @@
+# Debugging
+
+## Logging
+
+Cargo uses the [`env_logger`] crate to display debug log messages. The
+`CARGO_LOG` environment variable can be set to enable debug logging, with a
+value such as `trace`, `debug`, or `warn`. It also supports filtering for
+specific modules. Feel free to use the standard [`log`] macros to help with
+diagnosing problems.
+
+```sh
+# Outputs all logs with levels debug and higher
+CARGO_LOG=debug cargo generate-lockfile
+
+# Don't forget that you can filter by module as well
+CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile
+
+# This will print lots of info about the download process. `trace` prints even more.
+CARGO_HTTP_DEBUG=true CARGO_LOG=cargo::ops::registry=debug cargo fetch
+
+# This is an important command for diagnosing fingerprint issues.
+CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build
+```
+
+[`env_logger`]: https://docs.rs/env_logger
+[`log`]: https://docs.rs/log

src/doc/contrib/src/implementation/filesystem.md

@@ -0,0 +1,21 @@
+# Filesystem
+
+Cargo tends to get run on a very wide array of file systems. Different file
+systems can have a wide range of capabilities, and Cargo should strive to do
+its best to handle them. Some examples of issues to deal with:
+
+* Not all file systems support locking. Cargo tries to detect if locking is
+  supported, and if not, will ignore lock errors. This isn't ideal, but it is
+  difficult to deal with.
+* The [`fs::canonicalize`] function doesn't work on all file systems
+  (particularly some Windows file systems). If that function is used, there
+  should be a fallback if it fails. This function will also return `\\?\`
+  style paths on Windows, which can have some issues (such as some tools not
+  supporting them, or having issues with relative paths).
+* Timestamps can be unreliable. The [`fingerprint`] module has a deeper
+  discussion of this. One example is that Docker cache layers will erase the
+  fractional part of the time stamp.
+* Symlinks are not always supported, particularly on Windows.
+
+[`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs
+[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html

src/doc/contrib/src/implementation/index.md

@@ -0,0 +1,6 @@
+# Implementing a Change
+
+This chapter gives an overview of what you need to know in making a change to cargo.
+
+If you feel something is missing that would help you, feel free to ask on
+[Zulip](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo).

src/doc/contrib/src/architecture/subcommands.md renamed to src/doc/contrib/src/implementation/subcommands.md

@@ -1,4 +1,4 @@
-# SubCommands
+# New Subcommands
 
 Cargo is a single binary composed of a set of [`clap`] subcommands. All
 subcommands live in [`src/bin/cargo/commands`] directory.