|
| 1 | +# Administrative Tasks |
| 2 | + |
| 3 | +This documentation is for Carol and Steve and anyone else managing the repo to remember how to do |
| 4 | +occasional maintenance tasks. |
| 5 | + |
| 6 | +## Update the `rustc` version |
| 7 | + |
| 8 | +- Change the version number in `.github/workflows/main.yml` |
| 9 | +- Change the version number in `rust-toolchain`, which should change the version you're using |
| 10 | + locally with `rustup` |
| 11 | +- Change the version number in `src/title-page.md` |
| 12 | +- Run `./tools/update-rustc.sh` (see its commented code for details on what it does) |
| 13 | +- Inspect the changes (by looking at the files changed according to git) and their effects (by |
| 14 | + looking at the files in `tmp/book-before` and `tmp/book-after`) and commit them if they look good |
| 15 | +- Grep for `manual-regeneration` and follow the instructions in those places to update output that |
| 16 | + cannot be generated by a script |
| 17 | + |
| 18 | +## Release a new version of the listings |
| 19 | + |
| 20 | +We now make `.tar` files of complete projects containing every listing available [as GitHub |
| 21 | +Releases](https://github.com/rust-lang/book/releases). To create a new release artifact, for |
| 22 | +example if there have been code changes due to edits or due to updating Rust and `rustfmt`, do the |
| 23 | +following: |
| 24 | + |
| 25 | +- Create a git tag for the release and push it to GitHub, or create a new tag by going to the |
| 26 | + GitHub UI, [drafting a new release](https://github.com/rust-lang/book/releases/new), and entering |
| 27 | + a new tag instead of selecting an existing tag |
| 28 | +- Run `cargo run --bin release_listings`, which will generate `tmp/listings.tar.gz` |
| 29 | +- Upload `tmp/listings.tar.gz` in the GitHub UI for the draft release |
| 30 | +- Publish the release |
| 31 | + |
| 32 | +## Add a new listing |
| 33 | + |
| 34 | +To facilitate the scripts that run `rustfmt` on all the listings, update the output when the |
| 35 | +compiler is updated, and produce release artifacts containing full projects for the listings, any |
| 36 | +listing beyond the most trivial should be extracted into a file. To do that: |
| 37 | + |
| 38 | +- Find where the new listing should go in the `listings` directory. |
| 39 | + - There is one subdirectory for each chapter |
| 40 | + - Numbered listings should use `listing-[chapter num]-[listing num]` for their directory names. |
| 41 | + - Listings without a number should start with `no-listing-` followed by a number that indicates |
| 42 | + its position in the chapter relative to the other listings without numbers in the chapter, then |
| 43 | + a short description that someone could read to find the code they're looking for. |
| 44 | + - Listings used only for displaying the output of the code (for example, when we say "if we had |
| 45 | + written x instead of y, we would get this compiler error:" but we don't actually show code x) |
| 46 | + should be named with `output-only-` followed by a number that indicates its position in the |
| 47 | + chapter relative to the other listings used only for output, then a short description that |
| 48 | + authors or contributors could read to find the code they're looking for. |
| 49 | + - **Remember to adjust surrounding listing numbers as appropriate!** |
| 50 | +- Create a full Cargo project in that directory, either by using `cargo new` or copying another |
| 51 | + listing as a starting point. |
| 52 | +- Add the code and any surrounding code needed to create a full working example. |
| 53 | +- If you only want to show part of the code in the file, use anchor comments (`// ANCHOR: some_tag` |
| 54 | + and `// ANCHOR_END: some_tag`) to mark the parts of the file you want to show. |
| 55 | +- For Rust code, use the `{{#rustdoc_include [fileame:some_tag]}}` directive within the code blocks |
| 56 | + in the text. The `rustdoc_include` directive gives the code that doesn't get displayed to |
| 57 | + `rustdoc` for `mdbook test` purposes. |
| 58 | +- For anything else, use the `{{#include [filename:some_tag]}}` directive. |
| 59 | +- If you want to display the output of a command in the text as well, create an `output.txt` file |
| 60 | + in the listing's directory as follows: |
| 61 | + - Run the command, like `cargo run` or `cargo test`, and copy all of the output. |
| 62 | + - Create a new `output.txt` file with the first line `$ [the command you ran]`. |
| 63 | + - Paste the output you just copied. |
| 64 | + - Run `./tools/update-rustc.sh`, which should perform some normalization on the compiler output. |
| 65 | + - Include the output in the text with the `{{#include [filename]}}` directive. |
| 66 | + - Add and commit output.txt. |
| 67 | +- If you want to display output but for some reason it can't be generated by a script (say, because |
| 68 | + of user input or external events like making a web request), keep the output inline but make a |
| 69 | + comment that contains `manual-regeneration` and instructions for manually updating the inline |
| 70 | + output. |
| 71 | +- If you don't want this example to even be attempted to be formatted by `rustfmt` (for example |
| 72 | + because the example doesn't parse on purpose), add a `rustfmt-ignore` file in the listing's |
| 73 | + directory and the reason it's not being formatted as the contents of that file (in case it's a |
| 74 | + rustfmt bug that might get fixed someday). |
| 75 | + |
| 76 | +## See the effect of some change on the rendered book |
| 77 | + |
| 78 | +To check, say, updating `mdbook` or changing the way files get included: |
| 79 | + |
| 80 | +- Generate a built book before the change you want to test by running `mdbook build -d |
| 81 | + tmp/book-before` |
| 82 | +- Apply the changes you want to test and run `mdbook build -d tmp/book-after` |
| 83 | +- Run `./tools/megadiff.sh` |
| 84 | +- Files remaining in `tmp/book-before` and `tmp/book-after` have differences you can manually |
| 85 | + inspect with your favorite diff viewing mechanism |
| 86 | + |
| 87 | +## Produce new markdown files for No Starch |
| 88 | + |
| 89 | +- Run `./tools/nostarch.sh` |
| 90 | +- Spot check the files that script created in the `nostarch` directory |
| 91 | +- Check them into git if you're starting a round of edits |
| 92 | + |
| 93 | +## Produce markdown from docx for diffing |
| 94 | + |
| 95 | +- TODO Carol to document this next time she does it |
| 96 | + |
| 97 | +## Generate Graphviz dot |
| 98 | + |
| 99 | +We're using [Graphviz](http://graphviz.org/) for some of the diagrams in the |
| 100 | +book. The source for those files live in the `dot` directory. To turn a `dot` |
| 101 | +file, for example, `dot/trpl04-01.dot` into an `svg`, run: |
| 102 | + |
| 103 | +```bash |
| 104 | +$ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg |
| 105 | +``` |
| 106 | + |
| 107 | +In the generated SVG, remove the width and the height attributes from the `svg` |
| 108 | +element and set the `viewBox` attribute to `0.00 0.00 1000.00 1000.00` or other |
| 109 | +values that don't cut off the image. |
0 commit comments