Skip to content

Commit d005448

Browse files
committed
Add a rustc-dev-guide chapter
1 parent 4d79542 commit d005448

File tree

3 files changed

+59
-0
lines changed

3 files changed

+59
-0
lines changed

src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
- [Triage and Prioritization](./compiler/prioritization.md)
6262
- [Working Areas](./compiler/working-areas.md)
6363
- [Operations](./compiler/operations.md)
64+
- [Rustc Dev Guide](./wg-rustc-dev-guide/README.md)
6465
- [crates.io](./crates-io/README.md)
6566
- [Crate removal](./crates-io/crate-removal.md)
6667
- [Database maintenance](./crates-io/db-maintenance.md)

src/wg-rustc-dev-guide/README.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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+
- Connect domain-specific doc changes with domain expert reviewers
11+
12+
## Review Policy
13+
14+
The dev guide has a much lower bar for changes to merged compared to the compiler itself. Incomplete
15+
and/or WIP documentation is preferred over no documentation. Stubbed out TODOs for sub-parts of chapters
16+
are useful to indicate known gaps in documentation that may otherwise leave the reader confused.
17+
18+
Contributors confident in the area being documented should also feel free to merge their own
19+
documentation without review. For this reason the dev guide does not have a reviewer automatically
20+
assigned to each PR, instead PR authors can manually request a PR reviewer if they believe it necessary.
21+
22+
A reviewer can be assigned by writing a comment containing: `r? rustc-dev-guide` or `r? @username`.
23+
24+
A good rule of thumb for whether you should feel comfortable merging your own rustc-dev-guide PR is whether
25+
you would feel comfortable approving an involved PR touching the relevant area of the compiler. See the
26+
compiler [review policy](../compiler/reviews.md).
27+
28+
## Subtree Syncs
29+
30+
The dev guide is a [josh](https://josh-project.github.io/josh/intro.html) subtree of the main rust-lang/rust
31+
repo. This makes it easier for compiler contributors to update documentation in the dev guide in tandem with
32+
changes to the compiler itself.
33+
34+
This necessitates a manual process of syncing any changes made to the dev guide between its own repo, and the
35+
copy maintained in the rust-lang/rust repo.
36+
37+
1. Wait at least a week since the last subtree sync took place.
38+
2. There will either be an automatically opened rustc-pull PR, or performing a rustc-pull encountered merge
39+
conflicts. If there is a rustc-pull PR open, merge it[^1], otherwise a manual rustc-pull should be performed.
40+
See [rustc-dev-guide#2451] for an example rustc-pull.
41+
3. Post in the [zulip channel for coordinating subtree syncs][subtree_coordination] that you're doing a sync
42+
4. Do a manual rustc-push and open the PR. The PR should be assigned to a rustc-dev-guide lead
43+
(currently @BoxyUwU or @jieyouxu). We tend to assign rustc-push PRs to people instead of self
44+
approving like some other teams. This is because there were some accidents when the subtree was originally
45+
setup so it felt scary to not have someone check things over.
46+
5. Post the rustc-push PR in the [zulip channel for coordinating subtree syncs][subtree_coordination] so everyone is aware that a subtree
47+
sync has been performed. See [rust-lang/rust#141962] for an example rustc-push.
48+
49+
50+
Documentation about *how* to perform a rustc-pull or rustc-push can be found in the dev guide's README.
51+
52+
[^1]: If the automatically opened rustc-pull doesn't contain any actual changes to the dev
53+
guide, then the subtree sync can be delayed until there are actual changes to sync.
54+
55+
[rust-lang/rust#141962]: https://github.com/rust-lang/rust/pull/141962
56+
[rustc-dev-guide#2451]: https://github.com/rust-lang/rustc-dev-guide/pull/2451
57+
[subtree_coordination]: https://rust-lang.zulipchat.com/#narrow/channel/196385-t-compiler.2Frustc-dev-guide/topic/Subtree.20sync.20automation/with/522133712

triagebot.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,4 @@ fallback = [
3232
"/src/platforms" = ["infra"]
3333
"/src/release" = ["release"]
3434
"/src/triagebot" = ["triagebot"]
35+
"/src/wg-rustc-dev-guide" = ["wg-rustc-dev-guide"]

0 commit comments

Comments
 (0)