Skip to content

Add a rustc-dev-guide chapter #873

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 5, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
58 changes: 58 additions & 0 deletions src/wg-rustc-dev-guide/README.md
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions triagebot.toml
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,4 @@ fallback = [
"/src/platforms" = ["infra"]
"/src/release" = ["release"]
"/src/triagebot" = ["triagebot"]
"/src/wg-rustc-dev-guide" = ["wg-rustc-dev-guide"]