Release r3

Author: lorensr

README.md

@@ -23,9 +23,10 @@ We welcome issues and PRs! For large changes, we recommend opening an issue firs
 If you're working on gitbook-related issues or want to see how your PR will be formatted, follow these steps to get set up after cloning:
 
 ```sh
-npm i -g gitbook
+npm i -g gitbook-cli
 gitbook install
 mkdir out/
+./build.sh
 ```
 
 ---

text/1.md

@@ -25,7 +25,7 @@ Why use GraphQL? It turns out that GraphQL is amazingly useful—it combines a n
 
 - **Flexible, explicit queries:** GraphQL puts the consumer of the API in full control over what data they receive. Instead of a REST endpoint that returns all the properties you could possibly want (and often links to more), you only get the properties you ask for.
 - **Type-safe, self-documenting API:** GraphQL APIs are type-safe and self-documenting: the schema you define is exposed as interactive documentation for private or public consumption.
-- **No more API endpoint sprawl:** Backend engineers also love GraphQL. Once you write the code for accessing a data type, you won’t have to re-implement it. You don’t have to make a new endpoint for each view—you can leave that work up to the client and the GraphQL execution model, which is implemented by your GraphQL server library.
+- **No more API endpoint sprawl:** Backend engineers also love GraphQL. Once you write the code for accessing a data type, you won’t have to re-implement it. You don’t have to make a new endpoint for each view—you can leave that work up to the client and the GraphQL execution model, which is implemented by your GraphQL server library. And you don’t have to make a new API for each new app—you can have a single GraphQL API that covers all your business data.
 - **Query consolidation:** A request for multiple data types can be combined into a single query that is executed in parallel on the server.
 - **Static query analysis:** GraphQL schemas allow you to statically analyze the queries in your codebase and guarantee that you’ll never break them.
 

text/6.md

@@ -17,12 +17,17 @@ This book is for most programmers. If you write software that fetches data from
 
 This book will be especially poignant to these groups of people:
 
-- Backend devs who work on REST APIs and write a lot of similar data-fetching code, or who maintain view-specific endpoints.
-- Frontend devs of medium- or large-sized apps who either: A) don’t use a caching library, and manually keep track of what data has already been fetched from the server, or B) use a cache, and write a lot of code to fetch data over REST and put it in the cache (we’re looking at you, Reduxers 👀😄).
+- Backend devs who work on REST APIs and who:
+  - write a lot of similar code to fetch data and format it into JSON,
+  - maintain view- or device-specific endpoints, or
+  - have multiple APIs that use overlapping business data.
+- Frontend devs who either: 
+  - don’t use a caching library, and manually keep track of what data has already been fetched from the server, or 
+  - use a cache, and write a lot of code to fetch data over REST and put it in the cache (we’re looking at you, Reduxers 👀😄).
 
 # Background
 
-We have a [Background](bg.md) section that provides concise introductions to various background topics. You’re welcome to either look through them now or individually as you go along—at the beginning of a section, you’ll find a list of topics it assumes knowledge of, like the [Anywhere: HTTP](5.md#anywhere-http) section, which has two listed:
+We have a [Background](bg.md) chapter that provides concise introductions to various background topics. You’re welcome to either look through them now or individually as you go along—at the beginning of a section, you’ll find a list of topics it assumes knowledge of, like the [Anywhere: HTTP](5.md#anywhere-http) section, which has two listed:
 
 > Background: [HTTP](bg.md#http), [JSON](bg.md#json)
 
@@ -37,9 +42,11 @@ Here’s a full list of the topics:
 * [SSR](bg.md#ssr)
 * [Latency](bg.md#latency)
 * [Webhooks](bg.md#webhooks)  
+* [Continuous integration](bg.md#continuous-integration)
 * [Authentication](bg.md#authentication)
   * [Tokens vs. sessions](bg.md#tokens-vs-sessions)
-  * [localStorage vs. cookies](bg.md#localstorage-vs-cookies)  
+  * [localStorage vs. cookies](bg.md#localstorage-vs-cookies)
+* [Browser performance](bg.md#browser-performance)
 
 Some, like *Git* and *Node*, are necessary for following along with the coding. Others, like *Tokens vs. sessions*, are nice to know, but not necessary.
 
@@ -65,22 +72,22 @@ Chapters [2](2.md) and [3](3.md) explain the language itself and its type system
 
 # The code
 
-We intersperse blocks of code throughout the text. When we add code to a file that we’ve shown previously, we often just display the additions and some context, with ellipses (…) in place of existing code. These additions will be clearest if you read the book with the code open in another window. Further, we believe people tend to learn better if they write things out themselves, so we encourage you to write out the code for each step, and get it working on your computer before moving on to the next step.
+We intersperse blocks of code throughout the text. When we add code to a file that we’ve shown previously, we often just display the additions and some context, with ellipses (`...`) in place of existing code. These additions will be clearest if you read the book with the code open in another window. Further, we believe humans usually learn better if they write things out themselves, so we encourage you to write out the code for each step, and get it working on your computer before moving on to the next step.
 
-We recommend the Chrome browser and the [VS Code](https://code.visualstudio.com/) editor.
+We recommend using Chrome and [VS Code](https://code.visualstudio.com/).
 
-If you’re reading this in epub or mobi format on your phone, turning sideways into landscape mode will help reduce code snippet wrapping.
+Code snippets are better formatted and sized in the PDF version of the book. If you’re reading this in EPUB or MOBI format on your phone, turning sideways into landscape mode will help reduce code snippet wrapping.
 
 ## Git
 
-In Chapters 6–11, you’ll learn through writing an app, step by step. Each chapter has its own repository. Each step has a branch in that repo, for example branch `0` is the starter template, branch `1` has the code you write in step 1, etc. The branches we link to in the text also have a version number, and have the format: `[step]_[version]`. When this version of the Guide was published, the version of the Chapter 6 code was `0.1.0`, so step 1 links to branch `1_0.1.0`.
+In Chapters 6–11, you’ll learn through writing an app, step by step. Each chapter has its own repository. Each step has a branch in that repo, for example branch `0` is the starter template, branch `1` has the code you write in step 1, etc. The branches we link to in the text also have a version number, and have the format: `[step]_[version]`. When this version of the Guide was published, the version of the Chapter 6 code was `0.1.0`, so step 1 linked to branch `1_0.1.0`. The current version of the code is `0.2.0`, so step 1 links to `1_0.2.0`.
 
-If you skip the beginning of Chapter 6 and go straight to the [Listing reviews](6.md#listing-reviews) section, it says to start with step 9 (`9_0.1.0`). So we can look at the app in that state with these terminal commands:
+If you skip the beginning of Chapter 6 and go straight to the [Listing reviews](6.md#listing-reviews) section, it says to start with step 9 (`9_0.2.0`). So we can look at the app in that state with these terminal commands:
 
 ```sh
 git clone https://github.com/GraphQLGuide/guide.git
 cd guide/
-git checkout 9_0.1.0
+git checkout 9_0.2.0
 npm install
 npm start
 ```
@@ -93,12 +100,12 @@ If we get stuck, we can look at the diff between step 9 and step 10 with GitHub
 
 which in our case would be:
 
-[`github.com/GraphQLGuide/guide/compare/9_0.1.0...10_0.1.0`](https://github.com/GraphQLGuide/guide/compare/9_0.1.0...10_0.1.0)
+[`github.com/GraphQLGuide/guide/compare/9_0.2.0...10_0.2.0`](https://github.com/GraphQLGuide/guide/compare/9_0.2.0...10_0.2.0)
 
 We can also see the solution to the current step by checking out the next step:
 
 ```sh
-git checkout 10_0.1.0
+git checkout 10_0.2.0
 npm start
 ```
 
@@ -119,9 +126,9 @@ Which means `'` instead of `"` for string literals and no unnecessary semicolons
 
 If you run into issues, we recommend posting to Stack Overflow with the relevant tag, for instance [`react-apollo`](https://stackoverflow.com/questions/ask?tags=react-apollo) for Chapter 6. If you have the Full edition, you can also ask the community in the #support Slack channel or email the technical support address we gave you.
 
-If the issue is with our code, please search the repository’s issues to see if it’s an existing bug, and if it’s new, submit it! 🙏🙌
+If the issue is with our code, please search the repository’s issues to see if it’s an existing bug, and if it’s new, submit it! 🙏 🙌
 
-[React repo issues](https://github.com/GraphQLGuide/guide/issues)
+[github.com/GraphQLGuide/guide/issues](https://github.com/GraphQLGuide/guide/issues)
 
 Another important resource is the docs! Here they are for each library:
 
@@ -133,18 +140,18 @@ Another important resource is the docs! Here they are for each library:
 
 # Version
 
-Book version: [`r2`](https://github.com/GraphQLGuide/book/releases)
+Book version: `r3` ([changelog](https://github.com/GraphQLGuide/book/releases))
 
-Published June 27, 2018
+Published April 10, 2019
 
-As we write more of the book, we’ll send you new versions of it (using the email address on the GitHub account you connected when you purchased the book at [graphql.guide](https://graphql.guide)).
+As we write more of the book, we’ll send you new versions of it (using the email address on the GitHub account you connected when you purchased the book from [graphql.guide](https://graphql.guide)).
 
 ## Chapter 6 
 
-Code version: [`0.1.0`](https://github.com/GraphQLGuide/guide/blob/master/CHANGELOG.md)
+Code version: `0.2.0` ([changelog](https://github.com/GraphQLGuide/guide/blob/master/CHANGELOG.md))
 
 ```
-react-apollo 2.1
-graphql 0.13
-react 16.3
+react-apollo 2.5
+graphql 0.14
+react 16.8
 ```

text/README.md

@@ -121,7 +121,7 @@
       * [Add new reviews](6.md#add-new-reviews)
       * [Update on edit and delete](6.md#update-on-edit-and-delete)
     * [Prefetching](6.md#prefetching)
-      * [On mouse over](6.md#on-mouse-over)
+      * [On mouseover](6.md#on-mouseover)
       * [Cache redirects](6.md#cache-redirects)
     * [Batching](6.md#batching)
     * [Persisting](6.md#persisting)

text/SUMMARY.md

@@ -17,7 +17,6 @@ Chapter contents:
   * [localStorage vs. cookies](bg.md#localstorage-vs-cookies)
 * [Browser performance](bg.md#browser-performance)
 
-
 ---
 
 This chapter provides concise introductions to various background topics. You’re welcome to either read them all up front or individually as you go along—at the beginning of a section, you’ll find a list of topics it assumes knowledge of, like the [Anywhere: HTTP](5.md#anywhere-http) section, which has two listed:
@@ -202,7 +201,40 @@ graphql(schema, query).then(result => {
 
 # HTTP
 
-HTTP is a format for sending messages over the Internet. It is used on top of two other message formats—IP (which has an *IP address* and routes the message to the right machine) and TCP (which has a port number and resends any messages that are lost in transit). An HTTP message adds a *method* (like `GET` or `POST`), a path (like `/graphql`), headers (like the `Bearer` header we use for [authentication](#authentication)), and a body (where GraphQL queries and responses go).
+HTTP is a format for sending messages over the Internet. It is used on top of two other message formats—IP (which has an *IP address* and routes the message to the right machine) and TCP (which has a port number and resends any messages that are lost in transit). An HTTP message adds a *method* (like `GET` or `POST`), a path (like `/graphql`), headers (like the `Bearer` header we use for [authentication](#authentication)), and a body (where GraphQL queries and responses go). 
+
+When we enter a URL like `http://graphql.guide/` into our browser, it goes through these steps:
+
+1. Browser asks DNS server what the IP address of `graphql.guide` is.
+2. DNS server responds with `104.27.191.39`.
+
+We can see for ourselves what the DNS server says using the `nslookup` command:
+
+```sh
+$ nslookup graphql.guide
+Server:         8.8.4.4
+Address:        8.8.4.4#53
+
+Non-authoritative answer:
+Name:   graphql.guide
+Address: 104.27.191.39
+```
+
+3. Browser sends out a message to the Internet that looks like this:
+
+```
+IP to 104.27.191.39
+TCP to port 80
+HTTP GET /
+```
+
+4. Internet routers look at the IP part, see it is addressed to `104.27.191.39`, and pass it off to a router that is closer to `104.27.191.39`.
+
+5. The message arrives at `104.27.191.39` (the IP address of the Guide server), which opens the message, sees that it's trying to connect to port 80, and passes the message to whatever server program (in this case a Node.js process) is listening at the port. 
+
+6. The server process sees that the client wants to GET /, the root path, and sends back an `index.html` to the client.
+
+> This process is a little simplified—it actually takes a separate round-trip message to set up the TCP connection, and for `graphql.guide`, the client is actually redirected to HTTPS at the beginning, which uses port 443 and sets up an SSL connection before sending HTTP GET /.
 
 # SPA
 
@@ -263,7 +295,7 @@ Then our server parses the JSON to figure out what happened. In this case, the `
 
 # Continuous integration
 
-While continuous integration (CI) technically means merging to master frequently, in modern web development it usually means the process of tests being run automatically on each commit. It's often done with a service like [CircleCI](https://circleci.com/) that monitors our commits on Github, runs the tests on their servers, and provides a webpage for each commit where we can view the test output. We can also set it up to do something after the test, such as:
+While continuous integration (CI) technically means merging to master frequently, in modern web development it usually means the process of tests being run automatically on each commit. It's often done with a service like [CircleCI](https://circleci.com/) that monitors our commits on GitHub, runs the tests, and provides a webpage for each commit where we can view the test output. We can also set it up to do something after the test, such as:
 
 - Mark a pull request as passing or failing the tests.
 - Mark that commit as passing or failing by adding a red X or green checkmark next to the commit in the repository's history.
@@ -311,18 +343,18 @@ While the XSS issue is a serious concern, a common mitigation is setting short e
 
 # Browser performance
 
-Users notice when sites are slow, and they don't like it 😄. So if we want our users to feel good using our site, we want things in the browser to happen at a certain speed. 
+Users notice when sites are slow, and they don't like it 😄. So if we want our users to feel good using our site, we want different things in the browser to happen at certain speeds. 
 
 First let's go over how the browser works. Because JavaScript is single-threaded, it can only run on a single CPU core. We can have particular pieces of JS run in [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), which can run on different cores, but most of our JS runs on one core, in the browser's **main thread**. The browser also needs to do most of its page **rendering** (parsing HTML and CSS, laying out elements, painting pixels into images, etc) in the main thread. 
 
 > **Composition**, in which the pixel images are positioned, happens on the GPU.
 
 A CPU core has a limited speed—it can only do a certain amount of work each millisecond. And because both JS and rendering happen on the same core, every millisecond our JS takes up is another millisecond the browser rendering has to wait before it can run. And the user won't see the page update until the browser has a chance to render.
 
-Now that we know what's going on, let's think about different situations the user is in, and how fast our site should be in each:
+Now that we know what's going on, let's think about different situations the user is in and how fast our site should be in each:
 
 - **Page load:** The faster the better, but good targets are under 5 seconds *time to interactive* (the page is interactive when content has been displayed and the page is interactable—it can be scrolled, things can be clicked on, etc.) for the first visit and under 2 seconds for subsequent visits.
-- **Response:** When humans take an action like clicking a button, and the page changes within 100 milliseconds, they generally perceive the response as immediate. If the response takes over 100ms, humans perceive a delay. If our event handler runs code that takes 100ms on slow devices, then we want to break the code into two pieces: the minimum amount that will trigger the desired UI change, and the rest. And we schedule the rest to be done later:
+- **Response:** When humans take an action like clicking a button, and the page changes within 100 milliseconds, they generally perceive the response as immediate. If the response takes over 100ms, humans perceive a delay. If our click event handler runs code that takes 100ms on slow devices, then we want to break the code into two pieces: the minimum amount that will trigger the desired UI change, and the rest. And we schedule the rest to be done later:
 
 ```js
 button.onclick = () => {
@@ -342,6 +374,6 @@ class Foo extends Component {
 }
 ```
 
-[requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) runs the given function when the browser is idle, after it has finished rendering the changes triggered by `updateUI()`.
+[requestIdleCallback()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback) runs the given function when the browser is idle, after it has finished rendering the changes triggered by `updateUI()`/`this.setState()`.
 
-- **Animation:** Humans perceive a motion as smooth at 60 fps—when 60 frames are rendered per second. If we take 1000 milliseconds and divide by 60, we get 16. So while something is moving on the page, we want the browser to be able to render every 16ms. The browser needs 6ms to paint, which gives us 10ms left to run JS in. "Something moving" includes visual animations like entrances/exits and loading indicators, scrolling, and dragging.
+- **Animation:** Humans perceive a motion as smooth at 60 fps—when 60 frames are rendered per second. If we take 1000 milliseconds and divide by 60, we get 16. So while something is moving on the page, we want the browser to be able to render every 16ms. The browser needs 6ms to paint, which gives us 10ms left to run JS in. "Something moving" includes visual animations like entrances/exits and loading indicators, scrolling, and dragging.