-
Notifications
You must be signed in to change notification settings - Fork 196
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
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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). | ||
jieyouxu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.