Auto merge of #14222 - epage:contrib, r=weihanglo

docs(contrib): Document things I look for in RFCs

### What does this PR try to resolve?

Trying to make the RFC experience more pleasant by being upfront about things they need to take into account, rather than waiting for Cargo team members to review it (which they can also miss considering these points).

Along the way, I ended up tweaking the unstable docs as they are a related part of the process.

### How should we test and review this PR?

### Additional information

Author: bors

src/doc/contrib/src/SUMMARY.md

@@ -6,6 +6,7 @@
 - [Process](./process/index.md)
     - [Working on Cargo](./process/working-on-cargo.md)
     - [Release process](./process/release.md)
+    - [Writing an RFC](./process/rfc.md)
     - [Unstable features](./process/unstable.md)
     - [Security issues](./process/security.md)
 - [Design Principles](./design.md)

src/doc/contrib/src/process/index.md

@@ -114,6 +114,6 @@ on how this works.
 [issue-feature-request]: https://github.com/rust-lang/cargo/labels/C-feature-request
 [Feature accepted]: https://github.com/rust-lang/cargo/labels/Feature%20accepted
 [design principles chapter]: ../design.md
-[RFC process]: https://github.com/rust-lang/rfcs/
+[RFC process]: ./rfc.md
 [irlo]: https://internals.rust-lang.org/
 [subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands

src/doc/contrib/src/process/rfc.md

@@ -0,0 +1,64 @@
+# Writing an RFC
+
+Generally, an RFC goes through:
+1. Pre-RFC discussions on the [internals forum][irlo]
+2. [RFC]
+3. [Development and stabilization][unstable]
+
+Please keep in mind our [design principles](../design.md).
+
+For more concrete areas of consideration:
+
+## `.cargo/config.toml` and `Cargo.toml`
+
+`.cargo/config.toml` is for environment or transient configuration,
+being dependent on what directory you are running from and settable on the command-line,
+independent of other flags like `--manifest-path` or `--package`.
+
+On the other hand `Cargo.toml` is for static, high-level project configuration.
+
+For example,
+- [RFC 3537] chose
+  configuration for the MSRV-aware resolver because users would likely need
+  to change this setting, like in CI to verify the opposite case of
+  what they run by default.
+- The Cargo team rejected a [`[cfg]` table][cfg table] to represent `rustc`
+  `--cfg` flags as it was a direct port of low-level rustc behavior that didn't
+  mesh with the other high level abstractions of manifests.
+  - For stabilization, this was worked around through a build script directive and a `[lints]` field configuration.
+- [#12738][cargo#12738] for exploring how existing config might be representable in `Cargo.toml`.
+
+
+[irlo]: https://internals.rust-lang.org/
+[RFC]: https://github.com/rust-lang/rfcs/
+[unstable]: unstable.md
+[RFC 3537]: https://rust-lang.github.io/rfcs/3537-msrv-resolver.html
+[cfg table]: https://github.com/rust-lang/cargo/pull/11631#issuecomment-1487424886
+[cargo#12738]: https://github.com/rust-lang/cargo/issues/12738
+
+## `Cargo.toml`
+
+When adding a table to a manifest,
+- Should it be inheritable?
+- Ensure the package table and the inheritable table under `workspace` align
+- Care is needed to ensure a `workspace = true` field doesn't conflict with other entries
+  - e.g. [RFC 3389] had to explicitly exclude ever supporing a `workspace` linter
+
+When adding a field,
+- Is it inheritable?
+  - Consider whether sharing of the field would be driven by requirements or is a manifestion of the current implementation.
+    For example, in most cases, dependency sources (e.g. `version` field) should be aligned across a workspace
+    However, frequently dependency `features` will vary across a workspace.
+- When inheriting, can specify it in your package?
+- How does specifying a field in both `workspace` and a package interact?
+  - e.g. dependency sources cannot be overridden
+  - e.g. dependency `features` get merged
+  - e.g. depedency `default-features` has been hard to get right ([#12162][cargo#12162])
+
+When working extending `dependencies` tables:
+- How does this affect `cargo add` or `cargo remove`?
+- How does this affect `[patches]` which are just modified dependencies?
+
+[RFC 3389]: https://rust-lang.github.io/rfcs/3389-manifest-lint.html
+[cargo#12162]: https://github.com/rust-lang/cargo/issues/12162
+

src/doc/contrib/src/process/unstable.md

@@ -5,27 +5,6 @@ feature will only be usable on the nightly channel, and requires a specific
 opt-in by the user. Small changes can skip this process, but please consult
 with the Cargo team first.
 
-## Unstable feature opt-in
-
-For features that require behavior changes or new syntax in `Cargo.toml`, then
-it will need a `cargo-features` value placed at the top of `Cargo.toml` to
-enable it. The process for adding a new feature is described in the
-[`features` module]. Code that implements the feature will need to manually
-check that the feature is enabled for the current manifest.
-
-For features that add new command-line flags, config options, or environment
-variables, then the `-Z` flags will be needed to enable them. The [`features`
-module] also describes how to add these. New flags should use the
-`fail_if_stable_opt` method to check if the `-Z unstable-options` flag has
-been passed.
-
-## Unstable documentation
-
-Every unstable feature should have a section added to the [unstable chapter]
-describing how to use the feature.
-
-[unstable chapter]: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md
-
 ## Tracking issues
 
 Each unstable feature should get a [tracking issue]. These issues are
@@ -58,20 +37,51 @@ something is only partially implemented, it may have both
 [S-accepted]: https://github.com/rust-lang/cargo/labels/S-accepted
 [S-waiting-on-feedback]: https://github.com/rust-lang/cargo/labels/S-waiting-on-feedback
 
+## Implementation
+
+See [Working on Cargo](working-on-cargo.md).
+
+During implementation and testing, you may find reasons to deviate from the RFC.
+Please call these out in the tracking issue, with links to more information justifying the change
+(e.g. see [workspace inheritance tracking issue]).
+
+[workspace inheritance tracking issue]: https://github.com/rust-lang/cargo/issues/8415
+
+#### Unstable feature opt-in
+
+For features that require behavior changes or new syntax in `Cargo.toml`, then
+it will need a `cargo-features` value placed at the top of `Cargo.toml` to
+enable it. The process for adding a new feature is described in the
+[`features` module]. Code that implements the feature will need to manually
+check that the feature is enabled for the current manifest.
+
+For features that add new command-line flags, config options, or environment
+variables, then the `-Z` flags will be needed to enable them. The [`features`
+module] also describes how to add these. New flags should use the
+`fail_if_stable_opt` method to check if the `-Z unstable-options` flag has
+been passed.
+
+#### Unstable documentation
+
+Every unstable feature should have a section added to the [unstable chapter]
+describing how to use the feature.
+This can also serve as a place for the final documentation to live until its stabilized.
+
+[unstable chapter]: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md
+
 ## Pre-Stabilization 
 
 Once an unstable feature is "complete", the search for users to test
-and give feedback begins. Testing notes should be written up to give users an
-idea of how to test the new feature. An example being the 
-[workspace inheritance testing notes] for workspace inheritance. Once testing
-notes have been written up you should make posts in various rust communities
-([rust subreddit], [users], [internals], etc). Example posts made for workspace
-inheritance: [reddit post], [users post], [internals post]. The unstable feature
-should also be added to [This Week in Rust]. This should be done by adding the
-label `call-for-testing` to the RFC for the feature and making a comment with a
-link to the testing notes and the tracking issue (as needed). If there is not an
-RFC, a pull request should be made to the [TWiR repo] adding the feature to the
-`Call for Testing` section ([example]).
+and give feedback begins:
+1. Write up test instructions for users, summarizing where the feature is useful, how to use it (with links to the unstable documentation), and if there are any areas of particular concern
+  - This could be on the tracking issue or in a dedicated issue for feedback
+  - e.g. [workspace inheritance testing notes]
+2. Call for testing
+  - In the RFC, link to the test instructions and label it with with `call-for-testing` to be picked up by [This Week in Rust]
+    - If there is not an RFC, a pull request should be made to the [TWiR repo]
+      adding the feature to the `Call for Testing` section ([example]).
+  - Post on various Rust communities ([rust subreddit], [users], [internals], etc)
+  - e.g. [reddit post], [users post], [internals post]
 
 [workspace inheritance testing notes]: https://github.com/rust-lang/cargo/blob/6d6dd9d9be9c91390da620adf43581619c2fa90e/src/doc/src/reference/unstable.md#testing-notes
 [rust subreddit]: https://www.reddit.com/r/rust/