Document behavior of multiple stability attributes on items

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[src/*]
+end_of_line = lf
+insert_final_newline = true
+max_line_length = 100
+
+[ci/*.sh]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1,10 @@
+# Set the default behavior, in case people don't have core.autocrlf set.
+* text=auto eol=lf
+
+# git grep shouldn't match entries in huge minified javascript
+*.min.js binary
+
+# Older git versions try to fix line endings on images, this prevents it.
+*.png binary
+*.jpg binary
+*.ico binary

.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  schedule:
+    # Run at 18:00 UTC every day
+    - cron: '0 18 * * *'
+
+jobs:
+  ci:
+    if: github.repository == 'rust-lang/rustc-dev-guide'
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.21
+      MDBOOK_LINKCHECK_VERSION: 0.7.6
+      MDBOOK_MERMAID_VERSION: 0.12.6
+      MDBOOK_TOC_VERSION: 0.11.2
+      DEPLOY_DIR: book/html
+      BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # linkcheck needs the base commit.
+          fetch-depth: 0
+
+      - name: Cache binaries
+        id: mdbook-cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin
+          key: ${{ runner.os }}-${{ env.MDBOOK_VERSION }}--${{ env.MDBOOK_LINKCHECK_VERSION }}--${{ env.MDBOOK_TOC_VERSION }}--${{ env.MDBOOK_MERMAID_VERSION }}
+
+      - name: Cache linkcheck
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/book/linkcheck
+          key: ${{ runner.os }}-${{ hashFiles('./book/linkcheck') }}
+
+      - name: Install latest nightly Rust toolchain
+        if: steps.mdbook-cache.outputs.cache-hit != 'true'
+        run: |
+          rustup update nightly
+          rustup override set nightly
+
+      - name: Install Dependencies
+        if: steps.mdbook-cache.outputs.cache-hit != 'true'
+        run: |
+          cargo install mdbook --version ${{ env.MDBOOK_VERSION }}
+          cargo install mdbook-linkcheck --version ${{ env.MDBOOK_LINKCHECK_VERSION }}
+          cargo install mdbook-toc --version ${{ env.MDBOOK_TOC_VERSION }}
+          cargo install mdbook-mermaid --version ${{ env.MDBOOK_MERMAID_VERSION }}
+
+      - name: Check build
+        run: mdbook build
+
+      - name: Deploy to gh-pages
+        if: github.event_name == 'push'
+        run: |
+          touch "${{ env.DEPLOY_DIR }}/.nojekyll"
+          cp CNAME "${{ env.DEPLOY_DIR }}"
+          cd "${{ env.DEPLOY_DIR }}"
+          rm -rf .git
+          git init
+          git config user.name "Deploy from CI"
+          git config user.email ""
+          git add .
+          git commit -m "Deploy ${GITHUB_SHA} to gh-pages"
+          git push --quiet -f "https://x-token:${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}" HEAD:gh-pages

.github/workflows/date-check.yml

@@ -0,0 +1,48 @@
+name: Date-Check
+
+on:
+  schedule:
+    # Run at noon UTC every 1st of the month
+    - cron: '00 12 01 * *'
+
+  # Allow manually starting the workflow
+  workflow_dispatch:
+
+jobs:
+  date-check:
+    if: github.repository == 'rust-lang/rustc-dev-guide'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Ensure Rust is up-to-date
+        run: |
+          rustup update stable
+
+      - name: Run `date-check`
+        working-directory: ci/date-check
+        run: |
+          cargo run -- ../../src/ > ../../date-check-output.txt
+
+      - name: Open issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            const rawText = fs.readFileSync('date-check-output.txt', { encoding: 'utf8' });
+            const title = rawText.split('\n')[0];
+            if (title != 'empty') {
+                const body = rawText.split('\n').slice(1).join('\n');
+                github.rest.issues.create({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  title,
+                  body,
+                });
+                console.log('Opened issue.');
+            } else {
+                console.log('No dates to triage.');
+            }

.gitignore

@@ -1 +1,9 @@
 book
+
+# prevent accidental changes
+book.toml
+
+ci/date-check/target/
+
+# Generated by check-in.sh
+pulls.json

.mailmap

@@ -0,0 +1,5 @@
+Jynn Nelson <[email protected]> <[email protected]>
+Jynn Nelson <[email protected]> <[email protected]>
+Jynn Nelson <[email protected]> <[email protected]>
+Jynn Nelson <[email protected]> <[email protected]>
+Jynn Nelson <[email protected]>

CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: If you use this guide, please cite it using these metadata.
+title: Rust Compiler Development Guide (rustc-dev-guide)
+abstract: A guide to developing the Rust compiler (rustc)
+authors:
+  - name: "The Rust Project Developers"
+date-released: "2018-01-16"
+license: "MIT OR Apache-2.0"
+repository-code: "https://github.com/rust-lang/rustc-dev-guide"

CNAME

@@ -0,0 +1 @@
+rustc-dev-guide.rust-lang.org

CODE_OF_CONDUCT.md

@@ -1,38 +1,3 @@
 # The Rust Code of Conduct
 
-A version of this document [can be found online](https://www.rust-lang.org/conduct.html).
-
-## Conduct
-
-**Contact**: [[email protected]](mailto:[email protected])
-
-* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic.
-* On IRC, please avoid using overtly sexual nicknames or other nicknames that might detract from a friendly, safe and welcoming environment for all.
-* Please be kind and courteous. There's no need to be mean or rude.
-* Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer.
-* Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works.
-* We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behaviour. We interpret the term "harassment" as including the definition in the <a href="http://citizencodeofconduct.org/">Citizen Code of Conduct</a>; if you have any lack of clarity about what might be included in that concept, please read their definition. In particular, we don't tolerate behavior that excludes people in socially marginalized groups.
-* Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member, please contact one of the channel ops or any of the [Rust moderation team](/team.html#Moderation) immediately. Whether you're a regular contributor or a newcomer, we care about making this community a safe place for you and we've got your back.
-* Likewise any spamming, trolling, flaming, baiting or other attention-stealing behaviour is not welcome.
-
-## Moderation
-
-
-These are the policies for upholding our community's standards of conduct. If you feel that a thread needs moderation, please contact the [Rust moderation team](/team.html#Moderation).
-
-1. Remarks that violate the Rust standards of conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.)
-2. Remarks that moderators find inappropriate, whether listed in the code of conduct or not, are also not allowed.
-3. Moderators will first respond to such remarks with a warning.
-4. If the warning is unheeded, the user will be "kicked," i.e., kicked out of the communication channel to cool off.
-5. If the user comes back and continues to make trouble, they will be banned, i.e., indefinitely excluded.
-6. Moderators may choose at their discretion to un-ban the user if it was a first offense and they offer the offended party a genuine apology.
-7. If a moderator bans someone and you think it was unjustified, please take it up with that moderator, or with a different moderator, **in private**. Complaints about bans in-channel are not allowed.
-8. Moderators are held to a higher standard than other community members. If a moderator creates an inappropriate situation, they should expect less leeway than others.
-
-In the Rust community we strive to go the extra step to look out for each other. Don't just aim to be technically unimpeachable, try to be your best self. In particular, avoid flirting with offensive or sensitive issues, particularly if they're off-topic; this all too often leads to unnecessary fights, hurt feelings, and damaged trust; worse, it can drive people away from the community entirely.
-
-And if someone takes issue with something you said or did, resist the urge to be defensive. Just stop doing what it was they complained about and apologize. Even if you feel you were misinterpreted or unfairly accused, chances are good there was something you could've communicated better — remember that it's your responsibility to make your fellow Rustaceans comfortable. Everyone wants to get along and we are all here first and foremost because we want to talk about cool technology. You will find that people will be eager to assume good intent and forgive as long as you earn their trust.
-
-The enforcement policies listed above apply to all official Rust venues; including official IRC channels (#rust, #rust-internals, #rust-tools, #rust-libs, #rustc, #rust-beginners, #rust-docs, #rust-community, #rust-lang, and #cargo); GitHub repositories under rust-lang, rust-lang-nursery, and rust-lang-deprecated; and all forums under rust-lang.org (users.rust-lang.org, internals.rust-lang.org). For other projects adopting the Rust Code of Conduct, please contact the maintainers of those projects for enforcement. If you wish to use this code of conduct for your own project, consider explicitly mentioning your moderation policy or making a copy with your own moderation policy so as to avoid confusion.
-
-*Adapted from the [Node.js Policy on Trolling](http://blog.izs.me/post/30036893703/policy-on-trolling) as well as the [Contributor Covenant v1.3.0](http://contributor-covenant.org/version/1/3/0/).*
+This repository follows the [Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) of the Rust organization.

README.md

@@ -1,3 +1,108 @@
-An attempt to docuemnt how the compiler works. The intention is to
-bootstrap this "in repo" and eventually move the text over into the
-main rustc repo.
+[![CI](https://github.com/rust-lang/rustc-dev-guide/actions/workflows/ci.yml/badge.svg)](https://github.com/rust-lang/rustc-dev-guide/actions/workflows/ci.yml)
+
+
+This is a collaborative effort to build a guide that explains how rustc
+works. The aim of the guide is to help new contributors get oriented
+to rustc, as well as to help more experienced folks in figuring out
+some new part of the compiler that they haven't worked on before.
+
+[You can read the latest version of the guide here.](https://rustc-dev-guide.rust-lang.org/)
+
+You may also find the rustdocs [for the compiler itself][rustdocs] useful.
+Note that these are not intended as a guide; it's recommended that you search
+for the docs you're looking for instead of reading them top to bottom.
+
+[rustdocs]: https://doc.rust-lang.org/nightly/nightly-rustc
+
+For documentation on developing the standard library, see
+[`std-dev-guide`](https://std-dev-guide.rust-lang.org/).
+
+### Contributing to the guide
+
+The guide is useful today, but it has a lot of work still to go.
+
+If you'd like to help improve the guide, we'd love to have you! You can find
+plenty of issues on the [issue
+tracker](https://github.com/rust-lang/rustc-dev-guide/issues). Just post a
+comment on the issue you would like to work on to make sure that we don't
+accidentally duplicate work. If you think something is missing, please open an
+issue about it!
+
+**In general, if you don't know how the compiler works, that is not a
+problem!** In that case, what we will do is to schedule a bit of time
+for you to talk with someone who **does** know the code, or who wants
+to pair with you and figure it out.  Then you can work on writing up
+what you learned.
+
+In general, when writing about a particular part of the compiler's code, we
+recommend that you link to the relevant parts of the [rustc
+rustdocs][rustdocs].
+
+### Build Instructions
+
+To build a local static HTML site, install [`mdbook`](https://github.com/rust-lang/mdBook) with:
+
+```
+> cargo install mdbook mdbook-linkcheck mdbook-toc mdbook-mermaid
+```
+
+and execute the following command in the root of the repository:
+
+```
+> mdbook build --open
+```
+
+The build files are found in the `book/html` directory.
+
+### Link Validations
+
+We use `mdbook-linkcheck` to validate URLs included in our documentation.
+`linkcheck` will be run automatically when you build with the instructions in the section above.
+
+### Table of Contents
+
+We use `mdbook-toc` to auto-generate TOCs for long sections. You can invoke the preprocessor by
+including the `<!-- toc -->` marker at the place where you want the TOC.
+
+## How to fix toolstate failures
+
+> **NOTE**: Currently, we do not track the rustc-dev-guide toolstate due to
+[spurious failures](https://github.com/rust-lang/rust/pull/71731),
+but we leave these instructions for when we do it again in the future.
+
+1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4
+
+2. The commit contains a link to the PR that caused the breakage. e.g. https://github.com/rust-lang/rust/pull/64321
+
+3. If you go to that PR's thread, there is a post from bors with a link to the CI status: https://github.com/rust-lang/rust/pull/64321#issuecomment-529763807
+
+4. Follow the check-actions link to get to the Actions page for that build
+
+5. There will be approximately 1 billion different jobs for the build. They are for different configurations and platforms. The rustc-dev-guide build only runs on the Linux x86_64-gnu-tools job. So click on that job in the list, which is about 60% down in the list.
+
+6. Click the Run build step in the job to get the console log for the step.
+
+7. Click on the log and Ctrl-f to get a search box in the log
+
+8. Search for rustc-dev-guide. This gets you to the place where the links are checked. It is usually ~11K lines into the log.
+
+9. Look at the links in the log near that point in the log
+
+10. Fix those links in the rustc-dev-guide (by making a PR in the rustc-dev-guide repo)
+
+11. Make a PR on the rust-lang/rust repo to update the rustc-dev-guide git submodule in src/docs/rustc-dev-guide.
+To make a PR, the following steps are useful.
+
+```bash
+# Assuming you already cloned the rust-lang/rust repo and you're in the correct directory
+git submodule update --remote src/doc/rustc-dev-guide
+git add -u
+git commit -m "Update rustc-dev-guide"
+# Note that you can use -i, which is short for --incremental, in the following command
+./x test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway
+# Open a PR in rust-lang/rust
+```
+
+12. Wait for PR to merge
+
+Voilà!

book.toml

@@ -1,5 +1,58 @@
 [book]
-title = "Guide to Rustc Development"
-author = "Rustc developers"
-description = "A guide to developing rustc "
+title = "Rust Compiler Development Guide"
+author = "The Rust Project Developers"
+description = "A guide to developing the Rust compiler (rustc)"
 
+[build]
+create-missing = false
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+git-repository-url = "https://github.com/rust-lang/rustc-dev-guide"
+edit-url-template = "https://github.com/rust-lang/rustc-dev-guide/edit/master/{path}"
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+
+[output.html.search]
+use-boolean-and = true
+
+[output.html.fold]
+enable = true
+level = 0
+
+[output.linkcheck]
+command = "ci/linkcheck.sh"
+follow-web-links = true
+exclude = [
+    "crates\\.io",
+    "gcc\\.godbolt\\.org",
+    "youtube\\.com",
+    "youtu\\.be",
+    "dl\\.acm\\.org",
+    "cs\\.bgu\\.ac\\.il",
+    "www\\.amazon\\.com",
+    "www\\.rustaceans\\.org",
+    "play\\.rust-lang\\.org",
+    "tomlee\\.co",
+    "marketplace\\.visualstudio\\.com",
+    "objects\\.githubusercontent\\.com",
+    # The bug listing URL works only if an user is logged in, otherwise one gets 404.
+    "github\\.com/issues\\?",
+    # Handle: connection closed before message completed
+    "microsoft\\.com/en-us/research/publication/",
+]
+cache-timeout = 86400
+warning-policy = "error"
+
+[output.html.redirect]
+"/compiletest.html" = "tests/compiletest.html"
+"/diagnostics/sessiondiagnostic.html" = "diagnostic-structs.html"
+"/diagnostics/diagnostic-codes.html" = "error-codes.html"
+"/miri.html" = "const-eval/interpret.html"
+"/tests/integration.html" = "ecosystem.html"
+"/tests/headers.html" = "directives.html"