X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=CONTRIBUTING.md;h=9c4afcefa1f220a1754cddcc82d838e6102bff83;hb=4bde46e0e3a77d0ebf657aa110ff613130099ea7;hp=69ce9dae5aa9b939aadc9f6585ebe3d791746671;hpb=04c8191719761dd8617fb84a86fe114ed7ac6eab;p=rust.git diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69ce9dae5aa..9c4afcefa1f 100644 --- 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]. -### 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: -* 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 -(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 -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. -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: -* [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/) @@ -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 -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 @@ -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 -[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