Streamline "Getting Started" #1279
Merged
Conversation
This file contains 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
In "Getting Started", strip it back to the bare minimum. Some of this is moved into the later section. In the later section, add notable details like config.toml.example how and `profile` works. Also make the config.toml example more concise.
Less detail in "Getting Started", more in the later sections.
Less detail in "Getting Started", more in the later sections.
|
There's a lot more that could be done on this front. In particular the three "Building and Testing ..." sections of "Getting Started" contain a huge amount of detail, a lot of repetition just within themselves, as well as duplicating a lot of what's in later chapters. But I thought I'd start with some smaller pieces just to see what people's appetite is for changes of this sort :) |
|
This is way better than what we had, so I'm merging this.
Yeah, this is completely right. I've seen a ton of repetition and things there that could be improved. |
spastorino
approved these changes
Dec 24, 2021
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Jan 4, 2022
Update books ## reference 3 commits in 06f9e61931bcf58b91dfe6c924057e42ce273ee1..f8ba2f12df60ee19b96de24ae5b73af3de8a446b 2021-12-17 07:31:40 -0800 to 2022-01-03 11:02:08 -0800 - Switch the default edition for examples to 2021 (rust-lang/reference#1125) - Clarify behavior of x87 FP registers in inline assembly (rust-lang/reference#1126) - Add inline assembly to the reference (rust-lang/reference#1105) ## book 36 commits in 8a0bb3c96e71927b80fa2286d7a5a5f2547c6aa4..d3740fb7aad0ea4a80ae20f64dee3a8cfc0c5c3c 2021-12-22 20:54:27 -0500 to 2022-01-03 21:46:04 -0500 - Add a concrete example of an optional value. Fixes rust-lang/book#2848. - match isn't really an operator. Fixes rust-lang/book#2859 - Edits to edits of chapter 6 - Make fixes recommended by shellcheck - Use shellcheck - SIGH fix all the typos that were missed while spellcheck was broken - SIGH add all the words to the dictionary that were missed while spellcheck was broken - Remove test_harness from the dictionary - sigh, the xkcd sandwich one - Install aspell in CI - set -eu in all bash scripts - typo: assignement -> assignment - Fix quotes - Snapshot of ch12 for nostarch - Use 'static lifetime earlier because that's more correct. Fixes rust-lang/book#2864. - Add does_not_compile annotation to intermediate steps that don't compile - Sidestep who provides output streams. Fixes rust-lang/book#2933. - Remove note about primitive obsession. Fixes rust-lang/book#2863. - Remove sentence encouraging writing tests on your own. Fixes rust-lang/book#2223. - Bump mdBook version to 0.4.14 in workflow main.yml - Past tense make better sense - Past tense makes better sense - Update the edition in all the listings' Cargo.toml - Update the book to either say 2021 edition or not talk about editions - Remove most of the 2018 edition text from the title page. Fixes rust-lang/book#2852. - Fix word wrapping - Emphasize return type is mandatory - fix title capitalization - Further edits to mention of --include-ignored, propagate to src - feat: mention `cargo test -- --include-ignored` - wording: get rid of "to from" - interchanged position of `binary` and `library` - Fix wrong word typo - Further edits in rust-analyzer text - appendix-04 IDE integration: Replaced rls by rust-analyzer - Update link to Italian translation. Connects to rust-lang/book#2484. ## rustc-dev-guide 3 commits in 9bf0028..8754644 2021-12-20 21:53:57 +0900 to 2021-12-28 22:17:49 -0600 - Update link to moved section (rust-lang/rustc-dev-guide#1282) - Fix link in contributing.md (rust-lang/rustc-dev-guide#1280) - Streamline "Getting Started" (rust-lang/rustc-dev-guide#1279)
nnethercote
added a commit
to nnethercote/rustc-dev-guide
that referenced
this pull request
Jan 5, 2022
This is a follow-up to rust-lang#1279. The "Getting Started" chapter is, TBH, pretty bad when it comes to the stuff about building and testing. It has far too much detail and lots of repetition, which would be overwhelming to a newcomer. This commit removes most of it, leaving behind just quick mentions of the most common `x.py` commands: `check`, `build`, `test`, `fmt`, with links to the appropriate chapters for details. There were a few interesting details that weren't covered elsewhere, so I moved those into other chapters.
jyn514
pushed a commit
that referenced
this pull request
Jan 6, 2022
This is a follow-up to #1279. The "Getting Started" chapter is, TBH, pretty bad when it comes to the stuff about building and testing. It has far too much detail and lots of repetition, which would be overwhelming to a newcomer. This commit removes most of it, leaving behind just quick mentions of the most common `x.py` commands: `check`, `build`, `test`, `fmt`, with links to the appropriate chapters for details. There were a few interesting details that weren't covered elsewhere, so I moved those into other chapters.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
The "Getting Started" chapter begins with:
But this isn't true! For a lot of things the "Getting Started" chapter has as much or more detail than subsequent chapters.
This PR streamlines some parts of "Getting Started", so it genuinely is just a brief guide. Extraneous details are removed or moved into the appropriate later chapter.