Skip to content

Commit

Permalink
Update contributing information for 2018 edition
Browse files Browse the repository at this point in the history
  • Loading branch information
@steveklabnik
steveklabnik committed Apr 5, 2018
1 parent 57dcf3c commit 248579e
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 103 deletions.
123 changes: 52 additions & 71 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
57 changes: 25 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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).

0 comments on commit 248579e

Please sign in to comment.