rust-lang/book: the project says non error fixes may wait months or years

The book is printed, so between editions only error fixes are accepted

The contributing section contains the most important paragraph in the repository, and it is unusually direct about what will happen to your pull request.

It says that because the book is printed, and because the maintainers want to keep the online version close to the print version when possible, it may take longer than you are used to for an issue or pull request to be addressed.

Then the mechanism. So far the project has been doing a larger revision to coincide with the language's editions, and between those larger revisions it will only be correcting errors. The conclusion is the sentence to quote: if your issue or pull request is not strictly fixing an error, it might sit until the next larger revision, and the stated expectation is on the order of months or years.

So the contribution model is a publishing schedule rather than a review queue. Error fixes are the fast lane, and a well argued technical improvement is the slow one, and the project says so in advance rather than leaving you to discover it after a year.

The free online edition is a release snapshot and is behind this repository

The README says you can read the book for free online, and it gives three addresses, one each for the stable, beta and nightly release channels of the compiler. Those are the channels the book ships with.

Then the warning, which is the sentence that matters: be aware that issues in those versions may have been fixed in this repository already, as those releases are updated less frequently.

So there are two versions of the text and the hosted one is the older one. Anything merged here waits for the next release train to reach the page you read, which on a stable channel is a cadence measured in months and on a nightly channel is daily.

The practical consequence is a choice. Read the release channel to match the compiler you have installed, or read the repository if you want the current text and are willing to read something the publisher has not typeset yet. The README points at the release channels first and mentions the repository as the place where fixes may already be.

The tags are content milestones, not version numbers

There is no version number anywhere in this project's release history, and the three recent tags make that obvious. One is named for a print edition and dated December 2025. One is named for the addition of an asynchronous chapter and is dated November 2024. One is named for updating a dependency to a new major and is dated February 2021.

So the tags are a changelog expressed as git references, and the mix of content and dependency tags tells you how irregular the work is.

There is also a stated purpose for the releases page, which is not versioning. The README says to see the releases to download just the code of all the code listings that appear in the book. That is the feature a tag provides: a snapshot of the example code, named after whatever change produced it, which you can check out and run.

The consequence for a reader is that asking which version of the book you have has no answer in the tag list, and asking for the example code does.

The build needs a book tool version this repository does not state

The requirements section is short and it hands you off. Building the book requires the book tool, ideally the same version that the compiler project uses, and the link for that version points into the compiler repository's tooling manifest rather than into a number here.

The install command carries a placeholder where the version goes:

$ cargo install mdbook --locked --version <version_num>

The locked flag means the dependency graph will not be resolved loosely, and the placeholder means you have to read the other repository before you can run this one. That is a deliberate coupling: the book and the compiler share a rendering tool, and a mismatch shows up as pages that do not match what the maintainers see.

Building is then one command, and the output goes to a subdirectory you open in a browser, with the README giving the exact invocation for two browsers across Linux, OS X and two Windows shells. That is a complete local loop once you have the tool, and the tool version is the only part you have to go and find.

The doctests need a debug build the README never tells you to make

The book is a set of code examples, so a key check is that those examples run, and the README's way to run them is a doctest pass through the book tool.

The commands are two, and they change directory first:

$ cd packages/trpl
$ mdbook test --library-path packages/trpl/target/debug/deps

The library path is the important part. It points at a debug build output inside a package whose name is an abbreviation, which means you are expected to have compiled that package before the tests will find anything.

The README does not give the command that compiles it, and it does not say the tests are skipped when the path is missing. So a contributor following the README end to end will reach the test step, point the tool at a directory that does not exist, and get either an error or an empty pass, and neither tells them what is missing.

For a book whose value depends on correct code, it is worth getting this step working locally before opening a pull request.

Three generations of the book and a print edition share one tree

The repository root is a publishing pipeline rather than a single book, and the directory names say so. There is a directory for the first edition, one for the second, and one named for a year and an edition name. There is a directory for the print edition's source, and a directory for redirects, which is how old addresses for moved chapters keep working.

There is also a theme directory, so the site's appearance is a custom theme rather than the default, two files that style the project's mascot for light and dark, a configuration file for a general purpose formatter, a pinned toolchain file, a formatting configuration for the Rust inside the listings, a Cargo configuration directory, and two licence files with a separate copyright file.

Alongside the prose there are three administrative files: a tasks file, a to do file and a style guide. The style guide is the one contributors read for consistency, and its presence alongside a print edition is a reminder that this is edited copy rather than a wiki.

The build tooling is deliberately walled off. The Cargo workspace has exactly one member, a tools package, and its exclude list names the link checker because it belongs to continuous integration, the listings because they are intentionally separate from the workspace, and a temporary directory because that is where listings are built when the output is refreshed by a script.

Prose is spell-checked against a hand-kept dictionary, and translations wait on upstream

Two gates in the contributing section have nothing to do with Rust knowledge, and both are worth knowing before you open a pull request.

The first is spelling. There is a shell script in the continuous integration directory that scans the source files, and it needs a dictionary of valid words supplied as a text file beside it. If it reports a false positive, for example because you used a type name from the standard library, you have to add that word to the dictionary, and the README asks you to keep the file sorted for consistency.

So the prose gate is a hand-maintained word list, and a chapter about data structures needs a standard library type name added to it. That is a small, pleasant detail and it tells you the text is edited with the same care as the code.

The second is translations, and it is blocked upstream. The project invites help translating, points at a label for work in progress, and says to open an issue to start a new language. Then it says it is waiting on the book tool for support of multiple languages before any of them can be merged, and links to the upstream issue. So you can start a translation, and it will wait, for a reason that is not in this repository's control.

Editorial conclusion

Use this repository as the source of the book, and prefer the online edition tied to a compiler release over a random mirror, because the project maintains both and the online copy is a release snapshot. Do not open a feature pull request expecting a review, because the README says the book is printed, that larger revisions happen to coincide with language editions, and that between them only error fixes are handled, with a stated wait of months or years for anything else. Check three things before you contribute: whether your change is strictly an error fix, because that is the category the project says it works on; which toolchain you need, because the build requires a specific version of the book tool that the README refers you to another repository to find; and whether the code examples run, because the README's test step is a doctest run that expects a debug build of a package the README does not tell you to compile. The repository is not archived, the last push was 2026-10-28, and the newest tag is a print edition dated 2025-12-19.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. rust-lang/book on GitHub