Merge pull request #2097 from ehuss/contributor-guide

Add a contributor guide

Author: traviscross

.github/workflows/dev-guide.yml

@@ -0,0 +1,49 @@
+name: Deploy dev-guide
+on:
+  push:
+    branches:
+      - master
+
+env:
+  MDBOOK_VERSION: 0.5.2
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install mdbook
+      run: |
+        mkdir mdbook
+        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v${{ env.MDBOOK_VERSION }}/mdbook-v${{ env.MDBOOK_VERSION }}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+        echo `pwd`/mdbook >> $GITHUB_PATH
+
+    - name: Build the book
+      run: |
+        cd dev-guide
+        mdbook build
+        mkdir out
+        touch out/.nojekyll
+        mv book out/dev-guide
+
+    - name: Upload Artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./dev-guide/out
+
+  deploy:
+    needs: build
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -4,7 +4,7 @@ on:
   merge_group:
 
 env:
-  MDBOOK_VERSION: 0.5.1
+  MDBOOK_VERSION: 0.5.2
 
 jobs:
   code-tests:
@@ -97,6 +97,23 @@ jobs:
     - name: Test tools
       run: cargo test
 
+  dev-guide:
+    name: dev-guide build check
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - name: Install mdbook
+      env:
+        MDBOOK_VERSION: 0.5.1
+      run: |
+        mkdir bin
+        curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
+        echo "$(pwd)/bin" >> $GITHUB_PATH
+    - name: Check dev-guide build
+      run: |
+        cd dev-guide
+        mdbook build
+
   preview:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
@@ -143,6 +160,7 @@ jobs:
       - code-tests
       - style-tests
       - mdbook-spec
+      - dev-guide
       # preview is explicitly excluded here since it doesn't run on merge
     runs-on: ubuntu-latest
     steps:

CONTRIBUTING.md

@@ -1,76 +1,3 @@
-Thank you for your interest in contributing to the Rust Reference!
+# Contributing to The Rust Reference
 
-There are a few ways of helping with the reference: critiquing the reference,
-editing the reference, fixing incorrect information, adding examples and
-glossary entries, and documenting new or otherwise undocumented features in
-Rust.
-
-For a while, the Reference was basically ignored, and Rust continued gaining new
-features or changing old ones. It was also basically the introduction document
-before the first edition of the Rust book, and constantly in flux from the huge
-churn of the language design before v1.0.0. So there's a lot that's wrong, too
-teachy for people who should have basic understanding of Rust, or is too shallow
-for the Reference. As such, we have the warning saying there's work that needs
-to be done. Eventually, we plan to make sure everything is well documented
-enough that we can remove the warning.
-
-It is encouraged for you to read the [introduction] to familiarize yourself with
-the kind of content the reference is expected to contain and the conventions it
-uses. Also, the [Authoring Guide] provides more detailed guidelines for
-formatting and content.
-
-## Critiquing the Reference
-
-This is the easiest way to contribute. Basically, as you read the reference, if
-you find something confusing, incorrect, or missing, then you can file an issue
-against the reference explaining your concerns.
-
-## Editing the Reference
-
-Typos and incorrect links get through from time to time. Should you find them,
-we welcome PRs to fix them. Additionally, larger editing jobs that help remove
-the number of parentheticals, remove comma splices, italicize term definitions
-and other similar tasks are helpful.
-
-## Adding examples and glossary entries
-
-Examples are great. Many people will only read examples and ignore the prose.
-Ideally, every facet of every feature will have an example.
-
-Likewise, the reference has a glossary. It doesn't need to explain every facet
-of every feature nor contain every definition, but it does need to be expanded
-upon. Ideally entries in the glossary link to the associated documentation.
-
-## Adding documentation
-
-There are a lot of features that are not documented at all or are documented
-poorly. This is the hardest, but definitely most valuable. Pick an unassigned
-issue from the [issue tracker], and write about it.
-
-While writing, you may find it handy to have a [playpen] open to test out what
-you are documenting.
-
-Feel free to take information from the standard library and Rustonomicon as
-appropriate.
-
-Note that we don't write documentation for purely library features such as
-threads and IO and we don't write about Rust in the future. Documentation is
-written as if the current stable release of Rust is the last release. The
-`master` branch of the reference corresponds to what is **stable** on the
-`master` branch ("nightly") of [rust-lang/rust]. If you want to write about
-Rust in the future, you want [the Unstable book][unstable].
-
-## Stabilization
-
-When something that alters the language is stabilized, an issue should be
-opened on the reference [issue tracker] to track the documentation process.
-This should include links to any relevant information, such as the
-stabilization PR, the RFC, the tracking issue, and anything else that would be
-helpful for writing the documentation.
-
-[Authoring Guide]: docs/authoring.md
-[introduction]: src/introduction.md
-[issue tracker]: https://github.com/rust-lang/reference/issues
-[playpen]: https://play.rust-lang.org/
-[rust-lang/rust]: https://github.com/rust-lang/rust/
-[unstable]: https://doc.rust-lang.org/nightly/unstable-book/
+See the [Reference Developer Guide](https://rust-lang.github.io/reference/dev-guide/) for information on contributing to the Reference.

README.md

@@ -4,91 +4,4 @@ This document is the primary reference for the Rust programming language.
 
 ## Contributor docs
 
-There are several pages for those working on the reference:
-
-* [Authoring guide](https://github.com/rust-lang/reference/blob/master/docs/authoring.md): Guidelines for writing content.
-* [Review policy](https://github.com/rust-lang/reference/blob/master/docs/review-policy.md): Guidelines for reviewers.
-* [Grammar](https://github.com/rust-lang/reference/blob/master/docs/grammar.md): How the grammar syntax works.
-* [Attribute template](https://github.com/rust-lang/reference/blob/master/docs/attribute-template.md): The standard template for documenting an attribute.
-
-## Building
-
-To build the Reference, first clone the project:
-
-```sh
-git clone https://github.com/rust-lang/reference.git
-cd reference
-```
-
-(Alternatively, if you don't want to use `git`, [download][] a ZIP file
-of the project, extract it using your preferred tool, and rename the
-top-level directory to `reference`.)
-
-[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip
-
-### Installing mdbook
-
-The Reference is built using [mdbook].
-
-First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests:
-
-```sh
-rustup toolchain install nightly
-rustup override set nightly
-```
-
-Now, ensure you have `mdbook` installed, as this is needed in order to build the Reference:
-
-```sh
-cargo install --locked mdbook
-```
-
-[mdbook]: https://rust-lang.github.io/mdBook/
-
-### Running mdbook
-
-`mdbook` provides a variety of different commands and options to help you work on the book:
-
-* `mdbook build --open`: Build the book and open it in a web browser.
-* `mdbook serve --open`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser.
-
-The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See <https://rust-lang.github.io/mdBook/> for its usage.
-
-### `SPEC_RELATIVE`
-
-The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to <https://doc.rust-lang.org/> instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library.
-
-```sh
-SPEC_RELATIVE=0 mdbook serve --open
-```
-
-The published site at <https://doc.rust-lang.org/reference/> (or local docs using `rustup doc`) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in <https://doc.rust-lang.org/1.81.0/reference/> will stay within the 1.81.0 directory).
-
-### `SPEC_DENY_WARNINGS`
-
-The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content.
-
-### `SPEC_RUST_ROOT`
-
-The `SPEC_RUST_ROOT` can be used to point to the directory of a checkout of <https://github.com/rust-lang/rust>. This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked.
-
-## Running tests
-
-There are several different kinds of tests you can run (these are enforced on CI):
-
-* `mdbook test`: This will run the inline Rust codeblocks (internally it uses `rustdoc` to do this).
-* `cargo xtask style-check`: This will validate some style checks (see [authoring guide](docs/authoring.md)).
-* `cargo xtask linkcheck`: This will validate that markdown links aren't broken.
-* `cargo xtask test-all`: Runs all tests.
-
-## How is this published?
-
-The process for getting the reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is:
-
-1. Changes are merged to this repository.
-2. [Triagebot](https://forge.rust-lang.org/triagebot/doc-updates.html) will automatically synchronize this repository to [rust-lang/rust]. This happens every other week. The reference is tracked in [rust-lang/rust] as a [submodule](https://github.com/rust-lang/rust/tree/master/src/doc).
-  - This will open a PR on [rust-lang/rust] which needs to be merged, and that can take up to several days.
-3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be a part of that nightly release, and will be published after a few hours to <https://doc.rust-lang.org/nightly/reference/>.
-4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly will be promoted to beta (<https://doc.rust-lang.org/beta/reference/>), and then 6 weeks after that it will be promoted to stable (<https://doc.rust-lang.org/stable/reference/>).
-
-[rust-lang/rust]: https://github.com/rust-lang/rust/
+See the [Reference Developer Guide](https://rust-lang.github.io/reference/dev-guide/) for information on contributing to the Reference.

STYLE.md

@@ -0,0 +1,7 @@
+# The Rust Reference Developer Guide
+
+This is the source of the Reference Developer Guide, published at <https://rust-lang.github.io/reference/dev-guide/>. It is written in Markdown using [mdbook]. If you are editing these pages, the best way to view them is to run `mdbook serve --open`. This will start a web server on localhost that you can visit to view the book; it will automatically reload each time you edit a page.
+
+This is published via GitHub Actions to GitHub Pages.
+
+[mdbook]: https://rust-lang.github.io/mdBook/

dev-guide/README.md

@@ -0,0 +1,11 @@
+[book]
+title = "The Rust Reference Developer Guide"
+language = "en"
+
+[output.html]
+git-repository-url = "https://github.com/rust-lang/reference/tree/master/dev-guide"
+edit-url-template = "https://github.com/rust-lang/reference/edit/master/dev-guide/{path}"
+smart-punctuation = true
+
+[output.html.search]
+use-boolean-and = true

dev-guide/book.toml

@@ -0,0 +1,22 @@
+# Summary
+
+- [Introduction](introduction.md)
+- [Contribution process](process/index.md)
+  - [Stabilization process](process/stabilization.md)
+- [Publishing process](publishing.md)
+- [Reference tooling](tooling/index.md)
+  - [Building the Reference](tooling/building.md)
+  - [mdbook-spec](tooling/mdbook-spec.md)
+- [Tests](tests.md)
+- [Formatting](formatting/index.md)
+  - [Markdown](formatting/markdown.md)
+  - [Admonitions](formatting/admonitions.md)
+- [Language rules](rules/index.md)
+  - [rustc test annotations](rules/test-annotations.md)
+- [Examples](examples.md)
+- [Links](links.md)
+- [Rust grammar](grammar.md)
+- [Attributes](attributes.md)
+- [Style guide](style.md)
+- [Review policy](review-policy.md)
+- [Resources](resources.md)