diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9407266eb7..a4c64127e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,59 +1,37 @@ # Contributing -## First edition +We'd love your help! Thanks for caring about the book. -The first edition of the book is no longer actively being worked on, since -we're concentrating our efforts on bringing the second edition to print. We -will accept pull requests for small tweaks to the first edition; any larger -work should be spent improving the second edition. Issues will likely be closed -unless they are also issues in the second edition. +## Licensing -## Second edition +This repository is under the same license as Rust itself, MIT/Apache2. You +can find the full text of each license in the `LICENSE-*` files in this +repository. -We're currently working with No Starch Press to bring the second edition of the -book to print. Each chapter goes through [a number of stages][project]: +## Code of Conduct -[project]: https://github.com/rust-lang/book/projects/1 - -* We write and edit a chapter's initial content -* No Starch provides a round of edits and questions -* We revise, clarify, and check those edits -* A Technical Reviewer checks for the accuracy of technical details -* No Starch copyedits the chapter for spelling, grammar, wording, consistency -* We revise, clarify, and check the copyedits -* The chapter goes to layout, at which point only minor changes should be made - -### Documenting newly stabilized features - -New features added to Rust will be documented in the ["Newest Features" -Appendix][new] per [RFC 1636][rfc]. We'd love pull requests adding new -sections! These sections may be incorporated into the book at some point, but -we have no timeline for doing so; see the Post-publication section below for -more details. +The Rust project has [a code of conduct](http://rust-lang.org/conduct.html) +that governs all sub-projects, including this one. Please respect it! -[new]: https://github.com/rust-lang/book/blob/master/second-edition/src/appendix-06-newest-features.md -[rfc]: https://github.com/rust-lang/rfcs/pull/1636#issuecomment-247325313 +## Review -### Corrections and Modifications +Our [open pull requests][pulls] are new chapters or edits that we're +currently working on. We would love if you would read through those and make +comments for any suggestions or corrections! -We would love issues and pull requests to the Markdown files in the src -directory, up until the chapter goes to layout with No Starch. At that point, -we will likely only be accepting changes that correct factual errors or major -problems and not, for example, minor wording changes. - -You can check which chapters have gone to layout and are frozen on the [project -page][project] by scrolling all the way to the right to find the column titled -**Frozen**. +[pulls]: https://github.com/rust-lang/book/pulls -### Review +## Help wanted -Our [open pull requests][pulls] are new chapters or edits that we're currently -working on. We would love if you would read through those and make comments for -any suggestions or corrections! +If you're looking for ways to help that don't involve large amounts of +reading or writing, check out the [open issues with the E-help-wanted +label][help-wanted]. These might be small fixes to the text Rust code, +frontend code, or shell scripts that would help us be more efficient or +enhance the book in some way! -[pulls]: https://github.com/rust-lang/book/pulls +[help-wanted]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3AE-help-wanted -### Translations +## Translations We'd especially love help translating the second edition of the book! See the [Translations] label to join in efforts that are currently in progress. Open @@ -66,34 +44,37 @@ changes, so if you start with those, you won't have to redo work :) [mdbook support]: https://github.com/azerupi/mdBook/issues/5 [the frozen column]: https://github.com/rust-lang/book/projects/1 -### Help wanted +## Edition specific details -If you're looking for ways to help that don't involve large amounts of reading -or writing, check out the [open issues with the E-help-wanted -label][help-wanted]. These might be small fixes to the text Rust code, frontend -code, or shell scripts that would help us be more efficient or enhance the book -in some way! +Each edition of the book may be taking contributions, but only of certain +kinds depending on the edition. Read on to learn the details! -[help-wanted]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3AE-help-wanted +### Contributing to the 2018 Edition + +The 2018 is a "living" edition; it's not scheduled for in-print publication +at this time, and so is able to be updated at any time. We'd love pull +requests to fix issues with this edition, but we're not interested in +extremely large changes without discussing them first. If you'd like to make +a big change, please open an issue first! We'd hate for you to do some hard work +that we ultimately wouldn't accept. + +## Contributing to the Second Edition + +We're currently working with No Starch Press to bring the second edition of +the book to print. Each chapter goes through [a number of stages][project]. +At this This means we're not able to make large changes to chapters that are +in any column to the right of, and including, the "Frozen" column on that +board. + +[project]: https://github.com/rust-lang/book/projects/1 + +We *may* still able to make very small corrections that pertain to +correctness issues. If you find something, don't hesitate to open a pull +request, but we may not be able to accept it. You might want to check +in the 2018 edition to see if the corresponding error is still there, +and make the fix against that as well. + +## Contributing to the First Edition -### Post-publication - -After the second edition of the book goes to print, here are our intentions for -changes: - -* The online version should stay fairly close to the printed version. For - example, you should be able to look at listing 10-3 in the book and find - listing 10-3 in the online version and copy-paste the code if you want to - play with it. Major changes to correct errors should get documented in - errata. -* There are multiple efforts starting to translate the online book into - other languages. It would help the translations stay in sync if we're not - constantly changing the text. -* Someday there might be a third edition, once there are enough large, new - features in Rust to warrant such a thing. We don't have any schedule in mind - for that though, nor have we decided if it would be modifications to the - second edition or a ground-up rewrite. Until we have plans for that, we won't - be accepting pull requests that aren't fixing errors, for example, changing - the way something is worded. - -This repository is under the same license as Rust itself, MIT/Apache2. +The first edition is completely frozen, and not accepting changes. It's +mostly kept around for history's sake. diff --git a/README.md b/README.md index d7d5f28264..2563c6ceed 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,24 @@ -# NOTICE ABOUT STATUS - -The second edition of The Rust Programming Language is getting ever closer to being printed! -This means we're not able to make large changes to chapters that are in any column to the -right of, and including, the "Frozen" column [on our Project board][proj]. Issues or pull -requests submitted for frozen chapters are welcome but will be closed until we start work -on a third edition. Thank you! - -[proj]: https://github.com/rust-lang/book/projects/1 - # The Rust Programming Language [![Build Status](https://travis-ci.org/rust-lang/book.svg?branch=master)](https://travis-ci.org/rust-lang/book) -This repo contains two editions of “The Rust Programming Language”; we -recommend starting with the second edition. +This repository contains the source of all editions of "the Rust Programming +Language". -The second edition is a rewrite that will be printed by No Starch Press, -available around May 2018. Check [the No Starch Page][nostarch] for the latest -information on the release date and how to order. +The second edition will also be available in dead-tree form by No Starch +Press, available around May 2018. Check [the No Starch Page][nostarch] for +the latest information on the release date and how to order. [nostarch]: https://nostarch.com/rust -You can read the book for free online! Please see the book as shipped with the -latest [stable], [beta], or [nightly] Rust releases. Be aware that issues in -those versions may have been fixed in this repository already. - -[stable]: https://doc.rust-lang.org/stable/book/second-edition/ -[beta]: https://doc.rust-lang.org/beta/book/second-edition/ -[nightly]: https://doc.rust-lang.org/nightly/book/second-edition/ - -[The first edition is still available to read online][first]. - -[first]: https://doc.rust-lang.org/book/ +You can read all editions of the book for free online! Please see the book as +shipped with the latest [stable], [beta], or [nightly] Rust releases. Be +aware that issues in those versions may have been fixed in this repository +already, as those releases are updated less frequently. +[stable]: https://doc.rust-lang.org/stable/book/ +[beta]: https://doc.rust-lang.org/beta/book/ +[nightly]: https://doc.rust-lang.org/nightly/book/ ## Requirements @@ -48,9 +34,9 @@ $ cargo install mdbook --vers [version-num] ## Building -To build the book, first `cd` into either the `first-edition` or -`second-edition` directory depending on which edition of the book you would -like to build. Then type: +To build the book, first `cd` into one of the directory of the edition of the +book you'd like to build. For example, the `first-edition` or +`second-edition` directory. Then type: ```bash $ mdbook build @@ -86,6 +72,15 @@ $ mdbook test We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the kinds of contributions we're looking for. +### Second Edition + +The second edition of The Rust Programming Language is getting ever closer to being printed! + +### First Edition + +The first edition is frozen, and is not accepting any changes at this time. + + [contrib]: https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md ### Translations @@ -123,8 +118,6 @@ the word doc as markdown in order to backport changes to the online book: ## Graphviz dot -This is mostly for Carol's reference because she keeps having to look it up. - We're using [Graphviz](http://graphviz.org/) for some of the diagrams in the book. The source for those files live in the `dot` directory. To turn a `dot` file, for example, `dot/trpl04-01.dot` into an `svg`, run: @@ -143,4 +136,4 @@ To scan source files for spelling errors, you can use the `spellcheck.sh` script. It needs a dictionary of valid words, which is provided in `dictionary.txt`. If the script produces a false positive (say, you used word `BTreeMap` which the script considers invalid), you need to add this word to -`dictionary.txt` (keep the sorted order for consistency). +`dictionary.txt` (keep the sorted order for consistency). \ No newline at end of file