|
| 1 | +# Rustc Dev Guide |
| 2 | + |
| 3 | +The rustc-dev-guide working group is responsible for maintaining the rustc-dev-guide (located at |
| 4 | +[rust-lang/rustc-dev-guide](https://github.com/rust-lang/rustc-dev-guide)). This includes things such |
| 5 | +as: |
| 6 | +- Performing subtree syncs between the main rust repo and the rustc-dev-guide repo |
| 7 | +- Triaging the state of the guide to look for out of date information or missing information |
| 8 | +- Miscellaneous editorial work of the pages in the guide or fixing links that have bitrot |
| 9 | +- Reviewing simple PRs to the guide that don't need domain-specific expertise |
| 10 | + |
| 11 | +## Review Policy |
| 12 | + |
| 13 | +The dev guide has a much lower bar for changes to merged compared to the compiler itself. Incomplete |
| 14 | +and/or WIP documentation is preferred over no documentation. |
| 15 | + |
| 16 | +Contributors confident in the area being documented should also feel free to merge their own |
| 17 | +documentation without review. For this reason the dev guide does not have a reviewer automatically |
| 18 | +assigned to each PR, instead PR authors can manually request a PR reviewer if they believe it necessary. |
| 19 | + |
| 20 | +A reviewer can be assigned by writing a comment containing: `r? rustc-dev-guide`. |
| 21 | + |
| 22 | +A good rule of thumb for whether you should feel comfortable merging your own rustc-dev-guide PR is whether |
| 23 | +you would feel comfortable approving an involved PR touching the relevant area of the compiler. See the |
| 24 | +compiler [review policy](../compiler/reviews.md). |
| 25 | + |
| 26 | +## Subtree Syncs |
| 27 | + |
| 28 | +The dev guide is a [josh](https://josh-project.github.io/josh/intro.html) subtree of the main rust-lang/rust |
| 29 | +repo. This makes it easier for compiler contributors to update documentation in the dev guide in tandem with |
| 30 | +changes to the compiler itself. |
| 31 | + |
| 32 | +This necessitates a manual process of syncing any changes made to the dev guide between its own repo, and the |
| 33 | +copy maintained in the rust-lang/rust repo. |
| 34 | + |
| 35 | +1. Wait at least a week since the last subtree sync took place. |
| 36 | +2. There will either be an automatically opened rustc-pull PR, or performing a rustc-pull encountered merge |
| 37 | +conflicts. If there is a rustc-pull PR open, merge it[^1], otherwise a manual rustc-pull should be performed. |
| 38 | +See [rustc-dev-guide#2451] for an example rustc-pull. |
| 39 | +3. Post in the [zulip channel for coordinating subtree syncs][subtree_coordination] that you're doing a sync |
| 40 | +4. Do a manual rustc-push and open the PR. We tend to assign the rustc-push PRs to each other instead of self |
| 41 | +approving like some other times. This is because there were some accidents when the subtree was originally |
| 42 | +setup so it feels a little scary to not have someone check things over. |
| 43 | +5. Post the rustc-push PR in the [zulip channel for coordinating subtree syncs][subtree_coordination] so everyone is aware that a subtree |
| 44 | +sync has been performed. See [rust-lang/rust#141962] for an example rustc-push. |
| 45 | + |
| 46 | + |
| 47 | +Documentation about *how* to perform a rustc-pull or rustc-push can be found in the dev guide's README. |
| 48 | + |
| 49 | +[^1]: If the automatically opened rustc-pull doesn't contain any actual changes to the dev |
| 50 | +guide, then the subtree sync can be delayed until there are actual changes to sync. |
| 51 | + |
| 52 | +[rust-lang/rust#141962]: https://github.com/rust-lang/rust/pull/141962 |
| 53 | +[rustc-dev-guide#2451]: https://github.com/rust-lang/rustc-dev-guide/pull/2451 |
| 54 | +[subtree_coordination]: https://rust-lang.zulipchat.com/#narrow/channel/196385-t-compiler.2Frustc-dev-guide/topic/Subtree.20sync.20automation/with/522133712 |
0 commit comments