diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7b069575..2fc4b633 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -61,6 +61,7 @@ - [Triage and Prioritization](./compiler/prioritization.md) - [Working Areas](./compiler/working-areas.md) - [Operations](./compiler/operations.md) +- [Rustc Dev Guide](./wg-rustc-dev-guide/README.md) - [crates.io](./crates-io/README.md) - [Crate removal](./crates-io/crate-removal.md) - [Database maintenance](./crates-io/db-maintenance.md) diff --git a/src/wg-rustc-dev-guide/README.md b/src/wg-rustc-dev-guide/README.md new file mode 100644 index 00000000..27bde271 --- /dev/null +++ b/src/wg-rustc-dev-guide/README.md @@ -0,0 +1,58 @@ +# Rustc Dev Guide + +The rustc-dev-guide working group is responsible for maintaining the rustc-dev-guide (located at +[rust-lang/rustc-dev-guide](https://github.com/rust-lang/rustc-dev-guide)). This includes things such +as: +- Performing subtree syncs between the main rust repo and the rustc-dev-guide repo +- Triaging the state of the guide to look for out of date information or missing information +- Miscellaneous editorial work of the pages in the guide or fixing links that have bitrot +- Reviewing simple PRs to the guide that don't need domain-specific expertise +- Connect domain-specific doc changes with domain expert reviewers + +## Review Policy + +The dev guide has a much lower bar for changes to merged compared to the compiler itself. Incomplete +and/or WIP documentation is preferred over no documentation. Stubbed out TODOs with issues tracking +the missing pieces for sub-parts of chapters are useful to indicate known gaps in documentation that +may otherwise leave the reader confused. + +Contributors confident in the area being documented should also feel free to merge their own +documentation without review. For this reason the dev guide does not have a reviewer automatically +assigned to each PR, instead PR authors can manually request a PR reviewer if they believe it necessary. + +A reviewer can be assigned by writing a comment containing: `r? rustc-dev-guide` or `r? @username`. + +A good rule of thumb for whether you should feel comfortable merging your own rustc-dev-guide PR is whether +you would feel comfortable approving an involved PR touching the relevant area of the compiler. See the +compiler [review policy](../compiler/reviews.md). + +## Subtree Syncs + +The dev guide is a [josh](https://josh-project.github.io/josh/intro.html) subtree of the main rust-lang/rust +repo. This makes it easier for compiler contributors to update documentation in the dev guide in tandem with +changes to the compiler itself. + +This necessitates a manual process of syncing any changes made to the dev guide between its own repo, and the +copy maintained in the rust-lang/rust repo. + +1. Wait at least a week since the last subtree sync took place. +2. There will either be an automatically opened rustc-pull PR, or performing a rustc-pull encountered merge +conflicts. If there is a rustc-pull PR open, merge it[^1], otherwise a manual rustc-pull should be performed. +See [rustc-dev-guide#2451] for an example rustc-pull. +3. Post in the [zulip channel for coordinating subtree syncs][subtree_coordination] that you're doing a sync +4. Do a manual rustc-push and open the PR. The PR should be assigned to a rustc-dev-guide lead +(currently @BoxyUwU or @jieyouxu). We tend to assign rustc-push PRs to people instead of self +approving like some other teams. This is because there were some accidents when the subtree was originally +setup so it felt scary to not have someone check things over. +5. Post the rustc-push PR in the [zulip channel for coordinating subtree syncs][subtree_coordination] so everyone is aware that a subtree +sync has been performed. See [rust-lang/rust#141962] for an example rustc-push. + + +Documentation about *how* to perform a rustc-pull or rustc-push can be found in the dev guide's README. + +[^1]: If the automatically opened rustc-pull doesn't contain any actual changes to the dev +guide, then the subtree sync can be delayed until there are actual changes to sync. + +[rust-lang/rust#141962]: https://github.com/rust-lang/rust/pull/141962 +[rustc-dev-guide#2451]: https://github.com/rust-lang/rustc-dev-guide/pull/2451 +[subtree_coordination]: https://rust-lang.zulipchat.com/#narrow/channel/196385-t-compiler.2Frustc-dev-guide/topic/Subtree.20sync.20automation/with/522133712 \ No newline at end of file diff --git a/triagebot.toml b/triagebot.toml index acef24bd..fcc393c1 100644 --- a/triagebot.toml +++ b/triagebot.toml @@ -32,3 +32,4 @@ fallback = [ "/src/platforms" = ["infra"] "/src/release" = ["release"] "/src/triagebot" = ["triagebot"] +"/src/wg-rustc-dev-guide" = ["wg-rustc-dev-guide"]