Rollup merge of #71587 - matthewjasper:promoted-move-errors, r=nikomatsakis

[rust.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 69ce9dae5aa9b939aadc9f6585ebe3d791746671..9c4afcefa1f220a1754cddcc82d838e6102bff83 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -188,57 +188,73 @@ with one another are rolled up.
 Speaking of tests, Rust has a comprehensive test suite. More information about
 it can be found [here][rctd].
 
 Speaking of tests, Rust has a comprehensive test suite. More information about
 it can be found [here][rctd].
 

-### External Dependencies (subrepo)
+### External Dependencies (subtree)

 
 As a developer to this repository, you don't have to treat the following external projects
 differently from other crates that are directly in this repo:
 
 
 As a developer to this repository, you don't have to treat the following external projects
 differently from other crates that are directly in this repo:
 

-* none so far, see https://github.com/rust-lang/rust/issues/70651 for more info
+* Clippy

 
 They are just regular files and directories. This is in contrast to `submodule` dependencies
 
 They are just regular files and directories. This is in contrast to `submodule` dependencies

-(see below for those).
+(see below for those). Only tool authors will actually use any operations here.

 
 

-If you want to synchronize or otherwise work with subrepos, install the `git subrepo` command via
-instructions found at https://github.com/ingydotnet/git-subrepo
+#### Synchronizing a subtree

 
 

-#### Synchronizing a subrepo
+There are two synchronization directions: `subtree push` and `subtree pull`.

 
 

-There are two synchronization directions: `subrepo push` and `subrepo pull`. Both operations create
-a synchronization commit in the rustc repo.
-This commit is very important in order to make future synchronizations work.
-Do not rebase this commit under any circumstances.
-Prefer to merge in case of conflicts or redo the operation if you really need to rebase.
+```
+git subtree push -P src/tools/clippy git@github.com:your-github-name/rust-clippy sync-from-rust
+```

 
 

-A `git subrepo push src/tools/clippy`

 takes all the changes that
 happened to the copy in this repo and creates commits on the remote repo that match the local
 takes all the changes that
 happened to the copy in this repo and creates commits on the remote repo that match the local

-changes (so every local commit that touched the subrepo causes a commit on the remote repo).
+changes. Every local commit that touched the subtree causes a commit on the remote repo, but is
+modified to move the files from the specified directory to the tool repo root.
+
+Make sure to not pick the `master` branch on the tool repo, so you can open a normal PR to the tool
+to merge that subrepo push.
+
+```
+git subtree pull -P src/tools/clippy https://github.com/rust-lang/rust-clippy master
+```
+
+takes all changes since the last `subtree pull` from the tool repo
+repo and adds these commits to the rustc repo + a merge commit that moves the tool changes into
+the specified directory in the rust repository.
+
+It is recommended that you always do a push first and get that merged to the tool master branch.
+Then, when you do a pull, the merge works without conflicts.
+While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict
+resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to
+rebase the result of a `git subtree pull`, rebasing merge commits is a bad idea in general.

 
 

-A `git subrepo pull src/tools/clippy` takes all changes since the last `subrepo pull` from the clippy
-repo and creates a single commit in the rustc repo with all the changes.
+You always need to specify the `-P` prefix to the subtree directory and the corresponding remote
+repository. If you specify the wrong directory or repository
+you'll get very fun merges that try to push the wrong directory to the wrong remote repository.
+Luckily you can just abort this without any consequences by throwing away either the pulled commits
+in rustc or the pushed branch on the remote and try again. It is usually fairly obvious
+that this is happening because you suddenly get thousands of commits that want to be synchronized.

 
 

-#### Creating a new subrepo dependency
+#### Creating a new subtree dependency

 
 

-If you want to create a new subrepo dependency from an existing repository, call (from this
-repository's root directory!!)
+If you want to create a new subtree dependency from an existing repository, call (from this
+repository's root directory!)

 
 ```
 
 ```

-git subrepo clone https://github.com/rust-lang/rust-clippy.git src/tools/clippy
+git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master

 ```
 
 This will create a new commit, which you may not rebase under any circumstances! Delete the commit
 and redo the operation if you need to rebase.
 
 ```
 
 This will create a new commit, which you may not rebase under any circumstances! Delete the commit
 and redo the operation if you need to rebase.
 

-Now you're done, the `src/tools/clippy` directory behaves as if clippy were part of the rustc
-monorepo, so no one but you (or others that synchronize subrepos) needs to have `git subrepo`
-installed.
+Now you're done, the `src/tools/clippy` directory behaves as if Clippy were part of the rustc
+monorepo, so no one but you (or others that synchronize subtrees) actually needs to use `git subtree`.

 
 
 ### External Dependencies (submodules)
 
 Currently building Rust will also build the following external projects:
 
 
 
 ### External Dependencies (submodules)
 
 Currently building Rust will also build the following external projects:
 

-* [clippy](https://github.com/rust-lang/rust-clippy)

 * [miri](https://github.com/rust-lang/miri)
 * [rustfmt](https://github.com/rust-lang/rustfmt)
 * [rls](https://github.com/rust-lang/rls/)
 * [miri](https://github.com/rust-lang/miri)
 * [rustfmt](https://github.com/rust-lang/rustfmt)
 * [rls](https://github.com/rust-lang/rls/)


@@ -376,10 +392,18 @@ You can find documentation style guidelines in [RFC 1574][rfc1574].
 
 [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
 
 
 [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
 

-In many cases, you don't need a full `./x.py doc`. You can use `rustdoc` directly
-to check small fixes. For example, `rustdoc src/doc/reference.md` will render
-reference to `doc/reference.html`. The CSS might be messed up, but you can
-verify that the HTML is right.
+In many cases, you don't need a full `./x.py doc`, which will build the entire
+stage 2 compiler and compile the various books published on
+[doc.rust-lang.org]. When updating documentation for the standard library,
+first try `./x.py doc --stage 0 src/libstd`. If that fails, or if you need to
+see the output from the latest version of `rustdoc`, use `--stage 1` instead of
+`--stage 0`. Results should appear in `build/$TARGET/crate-docs`.
+
+[doc.rust-lang.org]: htts://doc.rust-lang.org
+
+You can also use `rustdoc` directly to check small fixes. For example,
+`rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.
+The CSS might be messed up, but you can verify that the HTML is right.

 
 Additionally, contributions to the [rustc-dev-guide] are always welcome. Contributions
 can be made directly at [the
 
 Additionally, contributions to the [rustc-dev-guide] are always welcome. Contributions
 can be made directly at [the


@@ -494,7 +518,7 @@ are:
 * Don't be afraid to ask! The Rust community is friendly and helpful.
 
 [rustc dev guide]: https://rustc-dev-guide.rust-lang.org/about-this-guide.html
 * Don't be afraid to ask! The Rust community is friendly and helpful.
 
 [rustc dev guide]: https://rustc-dev-guide.rust-lang.org/about-this-guide.html

-[gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/
+[gdfrustc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/

 [gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
 [rif]: http://internals.rust-lang.org
 [rr]: https://doc.rust-lang.org/book/README.html
 [gsearchdocs]: https://www.google.com/search?q=site:doc.rust-lang.org+your+query+here
 [rif]: http://internals.rust-lang.org
 [rr]: https://doc.rust-lang.org/book/README.html