Add a contributor guide#2097
Merged
traviscross merged 85 commits intorust-lang:masterfrom Feb 11, 2026
Merged
Conversation
rustbot
added
the
S-waiting-on-review
Member
|
30cb211 has wrong commit message |
tshepang
reviewed
Nov 25, 2025
ehuss
force-pushed
the
contributor-guide
branch
3 times, most recently
from
839f40c to
9b28ccc
Compare
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
ehuss
force-pushed
the
contributor-guide
branch
from
9b28ccc to
9951f64
Compare
This comment has been minimized.
This comment has been minimized.
ehuss
force-pushed
the
contributor-guide
branch
from
9951f64 to
a7a2033
Compare
traviscross
force-pushed
the
contributor-guide
branch
from
a7a2033 to
12f9af1
Compare
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This is the beginning of a new mdbook book that will house all of the guidelines for contributors. This is published via GitHub Pages.
This is just some light editing. I expect that this chapter will have larger edits in the future, but I want to defer that till later.
Our convention is to name the chapter by its title rather than saying "the X chapter". We capitalize the link text as a title but do not bold it because the target (examples.md) is within the dev-guide (an internal link).
Our convention is to name the section by its title rather than saying
"the X section". We capitalize the link text as a title and bold it
because the target is in the Reference proper (an external book). We
also add a brief locator ("in the Reference introduction") for
context, since the section name alone does not clearly indicate where
the content lives.
Our convention is to name the chapter by its title rather than saying "the X chapter". We capitalize the link text as a title and bold it because the target is the Notation chapter of the Reference proper (an external book). Let's also update the link definition label to match.
Our convention is to name chapters by their titles rather than saying "the X chapter". We capitalize the link text as titles but do not bold it, since both targets are within the dev-guide (internal links). Let's also update the link definition labels to match.
The CommonMark spec (§6.6) calls these "reference links" and "shortcut
reference links". The original phrasing ("The use of reference links
is preferred, with shortcuts if appropriate") is slightly stilted and
uses the informal abbreviation "shortcuts". This rewrites the
sentence for directness and uses the full CommonMark term "shortcut
reference links".
The original sentence ("Some of this information may already
exist... so there is no need to duplicate it") is vague about what
"it" refers to and where duplication should be avoided. Let's
clarify.
The original text says inline tests "will fail" without explaining why or when. The rewrite explains the mechanism.
The original phrasing ("Prefixed rule names should not be used in
tests") is unclear about what it means. What it really means is that
tests should use the most specific rule name available rather than a
parent name. The rewrite states this positively and gives a concrete
example.
The original phrasing ("Although it would be nice, it is unrealistic")
is a bit casual. Let's sharpen it up.
The original parenthetical ("written in itself, hopefully that's not
too confusing") is too casual and self-deprecating for a contributor
guide. The rewrite conveys the same information -- that the grammar
notation describes itself using its own notation -- more clearly and
concisely.
The original phrasing ("if you prefer to be more explicit") frames the
choice as a matter of personal preference. The rewrite frames it as a
matter of serving the reader: use the prefix when explicitness would
aid clarity. This better captures the intent.
The original sentence has an ambiguous "or" that conflates two conditions: "if the reviewer... is well-versed in the topic, or if the relevant experts are the author or have been heavily involved in the process." The reader cannot tell whether "well-versed in the topic" is an independent condition or part of the first clause. The rewrite separates the three conditions into a clear serial list and tightens the phrasing.
The original text says minor changes "can be made with the review from a team member without further consultation" but does not make clear that a maintainer may push fixes directly to the PR branch and merge without consulting the author. The rewrite makes this workflow explicit.
pnkfelix is no longer on the spec team or the lang team.
The style guide currently lives across three files (index.md, wording.md, punctuation.md) plus an empty "Language and grammar" placeholder. The content is small enough that a single file is better for now.
There's a new mdBook v0.5.2 release. It has various fixes we want. Let's bump our CI to use it.
traviscross
force-pushed
the
contributor-guide
branch
from
fc00519 to
a6c672d
Compare
traviscross
approved these changes
Feb 11, 2026
Contributor
|
Looks great. Thanks @ehuss. |
rustbot
removed
the
S-waiting-on-review
ehuss
added a commit
to ehuss/reference
that referenced
this pull request
Feb 13, 2026
This was missed in rust-lang#2097.
JonathanBrouwer
added a commit
to JonathanBrouwer/rust
that referenced
this pull request
Feb 24, 2026
Update books ## rust-embedded/book 1 commits in fe88fbb68391a465680dd91109f0a151a1676f3e..99d0341ff4e06757490af8fceee790c4ede50bc0 2026-02-11 12:58:13 UTC to 2026-02-11 12:58:13 UTC - Remove triagebot.toml (rust-embedded/book#405) ## rust-lang/reference 21 commits in addd0602c819b6526b9cc97653b0fadca395528c..442cbef9105662887d5eae2882ca551f3726bf28 2026-02-22 02:55:12 UTC to 2026-02-11 01:41:05 UTC - Document importing path-segment keyword (rust-lang/reference#2136) - avoid needless dereference (rust-lang/reference#2180) - Use `clobber_abi`s corresponding to the called functions in `[asm.abi-clobbers.many]`'s example. (rust-lang/reference#2170) - expr.paren.evaluation: fix and make more simple (rust-lang/reference#2158) - const-eval.const-context.outer-generics: make more clear/obvious (rust-lang/reference#2159) - Nightly test links: update rust branch name (use `main`) (rust-lang/reference#2185) - tools/xtask: update rust branch name for linkcheck script (use `main`) (rust-lang/reference#2184) - specify `if let` guards with updated scoping rules (rust-lang/reference#1957) - Document assignment expression as coercion site (rust-lang/reference#1954) - Remove exception WRT same-crate `non_exhaustive` reads (rust-lang/reference#2162) - Add negative lookahead (rust-lang/reference#2172) - Switch to new range syntax (rust-lang/reference#2173) - add mdbook output for dev-guide to ignore file (rust-lang/reference#2178) - Fix rule name for while syntax (rust-lang/reference#2175) - block-expr: add new rule expr.block.result-value (rust-lang/reference#2174) - lifetime-elision.md: add some missing periods (rust-lang/reference#2176) - Add cut operator (`^`) to grammar (rust-lang/reference#2104) - dev-guide stabilization.md: add missing "not" (rust-lang/reference#2167) - Add method call and await expr for Dot in syntax index (rust-lang/reference#2163) - Fix sort of punctuation list (rust-lang/reference#2161) - Add a contributor guide (rust-lang/reference#2097) ## rust-lang/rust-by-example 1 commits in bac931ef1673af63fb60c3d691633034713cca20..5383db524711c0c9c43c3ca9e5e706089672ed6a 2026-02-16 12:02:33 UTC to 2026-02-16 12:02:33 UTC - 1.2.2 Display: Fix typo in bonus instructions (before -> after) (rust-lang/rust-by-example#1998)
JonathanBrouwer
added a commit
to JonathanBrouwer/rust
that referenced
this pull request
Feb 24, 2026
Update books ## rust-embedded/book 1 commits in fe88fbb68391a465680dd91109f0a151a1676f3e..99d0341ff4e06757490af8fceee790c4ede50bc0 2026-02-11 12:58:13 UTC to 2026-02-11 12:58:13 UTC - Remove triagebot.toml (rust-embedded/book#405) ## rust-lang/reference 21 commits in addd0602c819b6526b9cc97653b0fadca395528c..442cbef9105662887d5eae2882ca551f3726bf28 2026-02-22 02:55:12 UTC to 2026-02-11 01:41:05 UTC - Document importing path-segment keyword (rust-lang/reference#2136) - avoid needless dereference (rust-lang/reference#2180) - Use `clobber_abi`s corresponding to the called functions in `[asm.abi-clobbers.many]`'s example. (rust-lang/reference#2170) - expr.paren.evaluation: fix and make more simple (rust-lang/reference#2158) - const-eval.const-context.outer-generics: make more clear/obvious (rust-lang/reference#2159) - Nightly test links: update rust branch name (use `main`) (rust-lang/reference#2185) - tools/xtask: update rust branch name for linkcheck script (use `main`) (rust-lang/reference#2184) - specify `if let` guards with updated scoping rules (rust-lang/reference#1957) - Document assignment expression as coercion site (rust-lang/reference#1954) - Remove exception WRT same-crate `non_exhaustive` reads (rust-lang/reference#2162) - Add negative lookahead (rust-lang/reference#2172) - Switch to new range syntax (rust-lang/reference#2173) - add mdbook output for dev-guide to ignore file (rust-lang/reference#2178) - Fix rule name for while syntax (rust-lang/reference#2175) - block-expr: add new rule expr.block.result-value (rust-lang/reference#2174) - lifetime-elision.md: add some missing periods (rust-lang/reference#2176) - Add cut operator (`^`) to grammar (rust-lang/reference#2104) - dev-guide stabilization.md: add missing "not" (rust-lang/reference#2167) - Add method call and await expr for Dot in syntax index (rust-lang/reference#2163) - Fix sort of punctuation list (rust-lang/reference#2161) - Add a contributor guide (rust-lang/reference#2097) ## rust-lang/rust-by-example 1 commits in bac931ef1673af63fb60c3d691633034713cca20..5383db524711c0c9c43c3ca9e5e706089672ed6a 2026-02-16 12:02:33 UTC to 2026-02-16 12:02:33 UTC - 1.2.2 Display: Fix typo in bonus instructions (before -> after) (rust-lang/rust-by-example#1998)
JonathanBrouwer
added a commit
to JonathanBrouwer/rust
that referenced
this pull request
Feb 24, 2026
Update books ## rust-embedded/book 1 commits in fe88fbb68391a465680dd91109f0a151a1676f3e..99d0341ff4e06757490af8fceee790c4ede50bc0 2026-02-11 12:58:13 UTC to 2026-02-11 12:58:13 UTC - Remove triagebot.toml (rust-embedded/book#405) ## rust-lang/reference 21 commits in addd0602c819b6526b9cc97653b0fadca395528c..442cbef9105662887d5eae2882ca551f3726bf28 2026-02-22 02:55:12 UTC to 2026-02-11 01:41:05 UTC - Document importing path-segment keyword (rust-lang/reference#2136) - avoid needless dereference (rust-lang/reference#2180) - Use `clobber_abi`s corresponding to the called functions in `[asm.abi-clobbers.many]`'s example. (rust-lang/reference#2170) - expr.paren.evaluation: fix and make more simple (rust-lang/reference#2158) - const-eval.const-context.outer-generics: make more clear/obvious (rust-lang/reference#2159) - Nightly test links: update rust branch name (use `main`) (rust-lang/reference#2185) - tools/xtask: update rust branch name for linkcheck script (use `main`) (rust-lang/reference#2184) - specify `if let` guards with updated scoping rules (rust-lang/reference#1957) - Document assignment expression as coercion site (rust-lang/reference#1954) - Remove exception WRT same-crate `non_exhaustive` reads (rust-lang/reference#2162) - Add negative lookahead (rust-lang/reference#2172) - Switch to new range syntax (rust-lang/reference#2173) - add mdbook output for dev-guide to ignore file (rust-lang/reference#2178) - Fix rule name for while syntax (rust-lang/reference#2175) - block-expr: add new rule expr.block.result-value (rust-lang/reference#2174) - lifetime-elision.md: add some missing periods (rust-lang/reference#2176) - Add cut operator (`^`) to grammar (rust-lang/reference#2104) - dev-guide stabilization.md: add missing "not" (rust-lang/reference#2167) - Add method call and await expr for Dot in syntax index (rust-lang/reference#2163) - Fix sort of punctuation list (rust-lang/reference#2161) - Add a contributor guide (rust-lang/reference#2097) ## rust-lang/rust-by-example 1 commits in bac931ef1673af63fb60c3d691633034713cca20..5383db524711c0c9c43c3ca9e5e706089672ed6a 2026-02-16 12:02:33 UTC to 2026-02-16 12:02:33 UTC - 1.2.2 Display: Fix typo in bonus instructions (before -> after) (rust-lang/rust-by-example#1998)
rust-timer
added a commit
to rust-lang/rust
that referenced
this pull request
Feb 24, 2026
Rollup merge of #153023 - rustbot:docs-update, r=ehuss Update books ## rust-embedded/book 1 commits in fe88fbb68391a465680dd91109f0a151a1676f3e..99d0341ff4e06757490af8fceee790c4ede50bc0 2026-02-11 12:58:13 UTC to 2026-02-11 12:58:13 UTC - Remove triagebot.toml (rust-embedded/book#405) ## rust-lang/reference 21 commits in addd0602c819b6526b9cc97653b0fadca395528c..442cbef9105662887d5eae2882ca551f3726bf28 2026-02-22 02:55:12 UTC to 2026-02-11 01:41:05 UTC - Document importing path-segment keyword (rust-lang/reference#2136) - avoid needless dereference (rust-lang/reference#2180) - Use `clobber_abi`s corresponding to the called functions in `[asm.abi-clobbers.many]`'s example. (rust-lang/reference#2170) - expr.paren.evaluation: fix and make more simple (rust-lang/reference#2158) - const-eval.const-context.outer-generics: make more clear/obvious (rust-lang/reference#2159) - Nightly test links: update rust branch name (use `main`) (rust-lang/reference#2185) - tools/xtask: update rust branch name for linkcheck script (use `main`) (rust-lang/reference#2184) - specify `if let` guards with updated scoping rules (rust-lang/reference#1957) - Document assignment expression as coercion site (rust-lang/reference#1954) - Remove exception WRT same-crate `non_exhaustive` reads (rust-lang/reference#2162) - Add negative lookahead (rust-lang/reference#2172) - Switch to new range syntax (rust-lang/reference#2173) - add mdbook output for dev-guide to ignore file (rust-lang/reference#2178) - Fix rule name for while syntax (rust-lang/reference#2175) - block-expr: add new rule expr.block.result-value (rust-lang/reference#2174) - lifetime-elision.md: add some missing periods (rust-lang/reference#2176) - Add cut operator (`^`) to grammar (rust-lang/reference#2104) - dev-guide stabilization.md: add missing "not" (rust-lang/reference#2167) - Add method call and await expr for Dot in syntax index (rust-lang/reference#2163) - Fix sort of punctuation list (rust-lang/reference#2161) - Add a contributor guide (rust-lang/reference#2097) ## rust-lang/rust-by-example 1 commits in bac931ef1673af63fb60c3d691633034713cca20..5383db524711c0c9c43c3ca9e5e706089672ed6a 2026-02-16 12:02:33 UTC to 2026-02-16 12:02:33 UTC - 1.2.2 Display: Fix typo in bonus instructions (before -> after) (rust-lang/rust-by-example#1998)
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
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.
This adds a new contributor guide. It is built with mdbook with the intention that it is published on GitHub Pages. This replaces several of the loosely organized documents that we have accumulated over time. It also adds some new content aimed at contributors, such as an overview of the contribution process.
Several of the chapters are essentially stubs or basic starting points with the intention that they get reworked in the future. There's also still a lot of work left to resolve the Meta issues.
Note that I am also working on a separate but closely related initiative to add a scope chapter to the Reference itself, along with a rework of the introduction. This is intended to further clarify to contributors (and readers!) what is expected of the content.