rust/book
1
0
Fork 0
mirror of https://github.com/rust-lang/book.git synced 2026-09-15 10:10:42 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #567 from rust-lang/contribution-clarifications

Browse Source 
Update contributing info
This commit is contained in:
Steve Klabnik
2017-03-27 12:55:39 -04:00
committed by GitHub
parent f75428ccea 62f78bb3f7
commit e51c91acde
5 changed files with 126 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
.github/ISSUE_TEMPLATE.md vendored
View File

@@ -1,16 +1,26 @@
## What to expect when you file an issue here
This is the repo for The Rust Programming Language, available at
https://doc.rust-lang.org/book/.
### First edition
## Editions
The first edition of the book is no longer being actively worked on.
There are two editions: first and second. The second is currently in
a draft state, the first edition is no longer being actively worked on.
Issues for the first edition of the book are worthwhile if you are planning to
submit a pull request, and want to discuss it first. But as we aren't actively
working on the first edition, general bugs will be closed.
Therefore, issues for the first edition of the book are worthwhile if you
are planning to submit a pull request, and want to discuss it first. But
as we aren't actively working on the first edition, general bugs will be
closed.
### Second edition
Thank you for reading, you may now delete this text!
For the second edition, we are currently working with No Starch Press to bring
it to print. Chapters go through a number of stages in the editing process, and
once they've gotten to the layout stage, they're effectively frozen.
For chapters that have gotten to the layout stage, we will likely only be
accepting changes that correct factual errors or major problems and not, for
example, minor wording changes.
Scroll all the way to the right on https://github.com/rust-lang/book/projects/1
to see which chapters have been frozen.
Please see CONTRIBUTING.md for more details.
Thank you for reading, you may now delete this text!

34
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@@ -1,18 +1,15 @@
## What to expect when you file an issue here
## What to expect when you open a pull request here
This is the repo for The Rust Programming Language, available at
https://doc.rust-lang.org/book/.
### First edition
## Editions
The first edition is no longer being actively worked on. We accept pull
requests for the first edition, but prefer small tweaks to large changes, as
larger work should be spent improving the second edition.
There are two editions: first and second. The second is currently in
a draft state, the first edition is no longer being actively worked on.
### Second edition
We accept pull requests for the first edition, but prefer small tweaks to
large changes, as larger work should be spent improving the second edition.
For the second edition, we are currently working with No Starch Press to bring it
to print. Chapters go through a number of stages in the editing process, and
For the second edition, we are currently working with No Starch Press to bring
it to print. Chapters go through a number of stages in the editing process, and
once they've gotten to the layout stage, they're effectively frozen.
For chapters that have gotten to the layout stage, we will likely only be
@@ -22,19 +19,6 @@ example, minor wording changes.
Scroll all the way to the right on https://github.com/rust-lang/book/projects/1
to see which chapters have been frozen.
After the book goes to print, here are our plans:
* The online version should stay close-ish 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, so if we were to leave PRs around unmerged, they might be
open indefinitely.
Please see CONTRIBUTING.md for more details.
Thank you for reading, you may now delete this text!

76
CONTRIBUTING.md
View File

@@ -1,7 +1,17 @@
# Contributing
We're currently working with No Starch Press to bring the book to print. Each
chapter goes through [a number of stages][project]:
## First edition
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.
## 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]:
[project]: https://github.com/rust-lang/book/projects/1
@@ -13,14 +23,18 @@ chapter goes through [a number of stages][project]:
* We revise, clarify, and check the copyedits
* The chapter goes to layout, at which point only minor changes should be made
### Corrections and Modifications
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.
The chapters we have planned but that we have not yet written appear greyed out
in the sidebar of the rendered book. We would love issues with ideas for what,
specifically, you'd like to see covered in those planned chapters!
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**.
### Review
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
@@ -28,11 +42,55 @@ any suggestions or corrections!
[pulls]: https://github.com/rust-lang/book/pulls
If you're looking for ways to help that don't involve reading or writing, check
out the [open issues with the E-help-wanted label][help-wanted]. These might be
Rust code, frontend code, or shell scripts that would help us be more efficient
or enhance the book in some way!
### 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
a new issue to start working on a new language! We're waiting on [mdbook
support] for multiple languages before we merge any in, but feel free to
start! The chapters in [the frozen column] of the project won't see major
changes, so if you start with those, you won't have to redo work :)
[Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
[mdbook support]: https://github.com/azerupi/mdBook/issues/5
[the frozen column]: https://github.com/rust-lang/book/projects/1
### Help wanted
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!
[help-wanted]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3AE-help-wanted
### 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.
* 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. Incorporating these sections might be what
the third edition ends up being, we're not sure yet.
[new]: https://github.com/rust-lang/book/blob/master/second-edition/src/appendix-07-newest-features.md
[rfc]: https://github.com/rust-lang/rfcs/pull/1636#issuecomment-247325313
This repository is under the same license as Rust itself, MIT/Apache2.

46
README.md
View File

@@ -2,15 +2,20 @@
[![Build Status](https://travis-ci.org/rust-lang/book.svg?branch=master)](https://travis-ci.org/rust-lang/book)
To read this book online, visit [rust-lang.github.io/book/][html].
This repo contains two editions of “The Rust Programming Language”.
The second edition is a rewrite that will be printed by NoStarch Press,
available around October 2017.
[You can read it online][html]; the last few chapters aren't completed yet, but
the first half of the book is much improved from the first edition. We recommend
starting with the second edition.
[html]: http://rust-lang.github.io/book/
This is the next iteration of “The Rust Programming Language” ([source][src],
[read online][prod]).
[The first edition is still available to read online][first].
[src]: https://github.com/rust-lang/rust/tree/master/src/doc/book
[prod]: https://doc.rust-lang.org/book/
[first]: https://doc.rust-lang.org/book/
## Requirements
@@ -24,8 +29,9 @@ $ cargo install mdbook
## 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 either the `first-edition` or
`second-edition` directory depending on which edition of the book you would
like to build. Then type:
```bash
$ mdbook build
@@ -58,18 +64,19 @@ $ mdbook test
## Contributing
We'd love your help! Please see [CONTRIBUTING.md][contrib].
We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the
kinds of contributions we're looking for.
[contrib]: https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md
### Translations
### Translations
We'd especially love help translating! See the [Translations][] label to join
in efforts that are currently in progress. Open a new issue to start
working on a new language! We're waiting on [mdbook support][] for multiple
languages before we merge any in, but feel free to start! The chapters in
[the frozen column][] of the project won't see major changes, so if you start
with those, you won't have to redo work :)
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
a new issue to start working on a new language! We're waiting on [mdbook
support] for multiple languages before we merge any in, but feel free to
start! The chapters in [the frozen column] of the project won't see major
changes, so if you start with those, you won't have to redo work :)
[Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
[mdbook support]: https://github.com/azerupi/mdBook/issues/5
@@ -77,8 +84,9 @@ with those, you won't have to redo work :)
## No Starch
As the book will be published by No Starch, we first iterate here, then ship the
text off to No Starch. Then they do editing, and we fold it back in.
As the second edition of the book will be published by No Starch, we first
iterate here, then ship the text off to No Starch. Then they do editing, and we
fold it back in.
As such, there’s a directory, *nostarch*, which corresponds to the text in No
Starch’s system.
@@ -91,7 +99,8 @@ the word doc as markdown in order to backport changes to the online book:
1. Accept all tracked changes
1. Save as Microsoft Word 2007-2013 XML (.docx) in the *tmp* directory
1. Run `./doc-to-md.sh`
1. Inspect changes made to the markdown file in the *nostarch* directory and copy the changes to the *src* directory as appropriate.
1. Inspect changes made to the markdown file in the *nostarch* directory and
copy the changes to the *src* directory as appropriate.
## Graphviz dot
@@ -116,4 +125,3 @@ 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).

4
second-edition/src/ch01-00-introduction.md
View File

@@ -28,6 +28,8 @@ well as how they work behind the scenes.
## Contributing to the book
This book is open source. If you find an error, please don’t hesitate to file an
issue or send a pull request [on GitHub].
issue or send a pull request [on GitHub]. Please see [CONTRIBUTING.md] for
more details.
[on GitHub]: https://github.com/rust-lang/book
[CONTRIBUTING.md]: https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md