Merge pull request #1 from reactjs/master

update

Author: swyxio

Diff for: .circleci/config.yml

@@ -0,0 +1,22 @@
+version: 2
+jobs:
+  build:
+    docker:
+      - image: circleci/node:latest
+    steps:
+      - checkout
+      - restore_cache:
+          keys:
+          - dependencies-{{ checksum "package.json" }}
+          # fallback to using the latest cache if no exact match is found
+          - dependencies-
+      - run:
+          name: Install
+          command: yarn install
+      - save_cache:
+          paths:
+            - node_modules
+          key: dependencies-{{ checksum "package.json" }}
+      - run:
+          name: Check Prettier, ESLint, Flow
+          command: yarn ci-check

Diff for: .eslintignore

@@ -4,4 +4,7 @@ node_modules/*
 content/*
 
 # Ignore built files
-public/*
+public/*
+
+# Ignore examples
+examples/*

Diff for: .eslintrc

@@ -1,7 +1,18 @@
 {
+  "extends": [
+    "fbjs"
+  ],
   "plugins": [
     "prettier",
     "react"
   ],
   "parser": "babel-eslint",
-}
+  "rules": {
+    "relay/graphql-naming": 0,
+    "max-len": 0
+  },
+  "env": {
+    "node": true,
+    "browser": true
+  }
+}

Diff for: .github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+
+
+<!--
+
+Thank you for the PR! Contributors like you keep React awesome!
+
+Please see the Contribution Guide for guidelines:
+
+https://github.com/reactjs/reactjs.org/blob/master/CONTRIBUTING.md
+
+If your PR references an existing issue, please add the issue number below
+
+-->

Diff for: .gitignore

@@ -1,4 +1,5 @@
 .cache
 .DS_STORE
+.idea
 node_modules
-public
+public

Diff for: .prettierrc.examples

@@ -0,0 +1,8 @@
+{
+  "bracketSpacing": false,
+  "jsxBracketSameLine": true,
+  "parser": "flow",
+  "printWidth": 60,
+  "singleQuote": true,
+  "trailingComma": "es5"
+}

Diff for: CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing
+
+Thank you for your interest in contributing to the React Docs!
+
+## Code of Conduct
+
+Facebook has adopted a Code of Conduct that we expect project
+participants to adhere to. Please [read the full text](https://code.facebook.com/codeofconduct)
+so that you can understand what actions will and will not be tolerated.
+
+## Guidelines for Text
+
+**Different sections intentionally have different styles.**
+
+The documentation is divided into sections to cater to different learning styles and use cases. When editing an article, try to match the surrounding text in tone and style. When creating a new article, try to match the tone of the other articles in the same section. Learn about the motivation behind each section below.
+
+**[Tutorial](https://reactjs.org/tutorial/tutorial.html)** is relatively informal, and is designed for people who prefer a hands-on approach to learning, and can tolerate skipping theory in favor of practice. Its goal is to give the reader a feel for a typical React workflow rather than to explain fundamentals in detail. Here we focus on *what* to do and spend less time on *how* or *why* we did it. It is extremely important to do a lot of hand-holding and unambiguously describe every single change. It should be possible for a beginner to mechanically follow every instruction, and still get to a working tic-tac-toe game.
+
+**[Quick Start](https://reactjs.org/docs/hello-world.html)** is designed to introduce fundamental concepts in a step-by-step way. Each individual article in Quick Start builds on the knowledge from the previous ones, so make sure not to add any "cyclical dependencies" between them. It is important that the reader can start with the first article and work their way to the last Quick Start article without ever having to "look ahead" for a definition. This explains some ordering choices (e.g. that state is explained before events, or that "thinking in React" doesn't use refs). Quick Start also serves as a reference manual for React concepts, so it is important to be very strict about their definitions and relationships between them. This is, for example, why we introduce elements before components. Resist adding too much detail to Quick Start articles. They intentionally don't cover all corner cases, and focus on establishing firm foundations.
+
+**[Advanced Guides](https://reactjs.org/docs/jsx-in-depth.html)** are deep dives into topics that aren't essential for a beginner developer but that everyone bumps into sooner or later. They don't have a specific order, and target more experienced developers. If you have a set of recipes fitting a particular use case, and those recipes aren't opinionated (most React users would agree on them), this is the place to add them.
+
+**[Reference](https://reactjs.org/docs/react-api.html)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Quick Start or Advanced Guides should be mentioned in the reference documentation for the corresponding APIs.
+
+**[Contributing](https://reactjs.org/docs/how-to-contribute.html)** should stay up-to-date and be friendly to relatively experienced developers.
+
+**[FAQ](https://reactjs.org/docs/faq-ajax.html)** has a more conversational tone than the other sections. Here, it's fine to include some content that's not primarily concerned with React, as long as React users are overwhelmingly interested in it (e.g. recommendations on directory structure). It's also okay to show more than a single way to do something in the FAQ, and briefly discuss the tradeoffs. The FAQ prioritizes unblocking people with a working solution over explaining concepts in detail, and can be more opinionated than the rest of the docs, even providing popular library recommendations.
+
+**Try to follow your own instructions.**
+
+When writing step-by-step instructions (e.g. how to install something), try to forget everything you know about the topic, and actually follow the instructions you wrote, a single step at time. Often you will discover that there is implicit knowledge that you forgot to mention, or that there are missing or out-of-order steps in the instructions. Bonus points for getting *somebody else* to follow the steps and watching what they struggle with. Often it would be something very simple that you have not anticipated.
+
+## Guidelines for Code Examples
+
+### Syntax
+
+#### Prefer JSX to `createElement`.
+
+Ignore this if you're specifically describing `createElement`.
+
+#### Use `const` where possible, otherwise `let`. Don't use `var`.
+
+Ignore this if you're specifically writing about ES5.
+
+#### Don't use ES6 features when equivalent ES5 features have no downsides.
+
+Remember that ES6 is still new to a lot of people. While we use it in many places (`const` / `let`, classes, arrow functions), if the equivalent ES5 code is just as straightforward and readable, consider using it.
+
+In particular, you should prefer named `function` declarations over `const myFunction = () => ...` arrows for top-level functions. However, you *should* use arrow functions where they provide a tangible improvement (such as preserving `this` context inside a component). Consider both sides of the tradeoff when deciding whether to use a new feature.
+
+#### Don't use features that aren't standardized yet.
+
+For example, **don't** write this:
+
+```js
+class MyComponent extends React.Component {
+  state = {value: ''};
+  handleChange = (e) => {
+    this.setState({value: e.target.value});
+  };
+}
+```
+
+Instead, **do** write this:
+
+```js
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props)
+    this.handleChange = this.handleChange.bind(this);
+    this.state = {value: ''};
+  }
+  handleChange(e) {
+    this.setState({value: e.target.value});
+  }
+}
+```
+
+Ignore this rule if you're specifically describing an experimental proposal. Make sure to mention its experimental nature in the code and in the surrounding text.
+
+### Style
+
+- Use semicolons.
+- No space between function names and parens (`method() {}` not `method () {}`).
+- When in doubt, use the default style favored by [Prettier](https://prettier.io/playground/).
+
+### Highlighting
+
+Use `js` as the highlighting language in Markdown code blocks:
+
+````
+```js
+// code
+```
+````
+
+Sometimes you'll see blocks with numbers.  
+They tell the website to highlight specific lines.
+
+You can highlight a single line:
+
+````
+```js{2}
+function hello() {
+  // this line will get highlighted
+}
+```
+````
+
+A range of lines:
+
+````
+```js{2-4}
+function hello() {
+  // these lines
+  // will get
+  // highlighted
+}
+```
+````
+
+Or even multiple ranges:
+
+````
+```js{2-4,6}
+function hello() {
+  // these lines
+  // will get
+  // highlighted
+  console.log('hello');
+  // also this one
+  console.log('there');
+}
+```
+````
+
+Be mindful that if you move some code in an example with highlighting, you also need to update the highlighting.
+
+Don't be afraid to often use highlighting! It is very valuable when you need to focus the reader's attention on a particular detail that's easy to miss.

Diff for: LICENSE.md

@@ -9,13 +9,13 @@ This repo contains the source code and documentation powering [reactjs.org](http
 1. Git
 1. Node: install version 8.4 or greater
 1. Yarn: See [Yarn website for installation instructions](https://yarnpkg.com/lang/en/docs/install/)
-1. A clone of the [reactjs.org repo](https://github.com/reactjs/reactjs.org) on your local machine
 1. A fork of the repo (for any contributions)
+1. A clone of the [reactjs.org repo](https://github.com/reactjs/reactjs.org) on your local machine
 
 ### Installation
 
 1. `cd reactjs.org` to go into the project root
-1. `yarn` to install the website's NPM dependencies
+1. `yarn` to install the website's npm dependencies
 
 ### Running locally
 
@@ -24,6 +24,10 @@ This repo contains the source code and documentation powering [reactjs.org](http
 
 ## Contributing
 
+### Guidelines
+
+The documentation is divided into several sections with a different tone and purpose. If you plan to write more than a few sentences, you might find it helpful to get familiar with the [contributing guidelines](https://github.com/reactjs/reactjs.org/blob/master/CONTRIBUTING.md#guidelines-for-text) for the appropriate sections.
+
 ### Create a branch
 
 1. `git checkout master` from any folder in your local `reactjs.org` repository
@@ -41,15 +45,21 @@ This repo contains the source code and documentation powering [reactjs.org](http
 ### Test the change
 
 1. If possible, test any visual changes in all latest versions of common browsers, on both desktop and mobile.
-1. Run `yarn check-all` from the project root. (This will run Prettier, ESlint, and Flow.)
+1. Run `yarn check-all` from the project root. (This will run Prettier, ESLint, and Flow.)
 
 ### Push it
 
 1. `git add -A && git commit -m "My message"` (replacing `My message` with a commit message, such as `Fixed header logo on Android`) to stage and commit your changes
 1. `git push my-fork-name the-name-of-my-branch`
 1. Go to the [reactjs.org repo](https://github.com/reactjs/reactjs.org) and you should see recently pushed branches.
 1. Follow GitHub's instructions.
-1. If possible include screenshots of visual changes. A Netlify build will also be automatically created once you make your PR so other people can see your change.
+1. If possible, include screenshots of visual changes. A Netlify build will also be automatically created once you make your PR so other people can see your change.
+
+## Translation
+
+If you are interesting in translating `reactjs.org`, please join the Crowdin.
+
+* [Crowdin - React](https://crowdin.com/project/react)
 
 ## Troubleshooting
 

Diff for: README.md

@@ -7,9 +7,15 @@ acdlite:
 benigeri:
   name: Paul Benigeri
   url: https://github.com/benigeri
+bvaughn:
+  name: Brian Vaughn
+  url: https://github.com/bvaughn
 chenglou:
   name: Cheng Lou
   url: https://twitter.com/_chenglou
+clemmy:
+  name: Clement Hoang
+  url: https://twitter.com/c8hoang
 Daniel15:
   name: Daniel Lo Nigro
   url: http://dan.cx/
@@ -63,7 +69,7 @@ sebmarkbage:
   url: https://twitter.com/sebmarkbage
 sophiebits:
   name: Sophie Alpert
-  url: https://sophiealpert.com
+  url: https://sophiebits.com/
 steveluscher:
   name: Steven Luscher
   url: https://twitter.com/steveluscher

Diff for: content/authors.yml

@@ -80,7 +80,7 @@ some pretty cool things with it:
   (including IE8) and automatically use
   [event delegation](http://davidwalsh.name/event-delegate).
 
-Head on over to https://reactjs.org to check out what we have
+Head on over to [https://reactjs.org](https://reactjs.org) to check out what we have
 built. Our documentation is geared towards building apps with the framework,
 but if you are interested in the nuts and bolts
 [get in touch](/support.html) with us!

Diff for: content/blog/2013-06-05-why-react.md

@@ -22,7 +22,7 @@ We've also published version `0.12.0-rc1` of the `react` and `react-tools` packa
 
 ## React Elements
 
-The biggest conceptual change we made in v0.12 is the move to React Elements. [We talked about this topic in depth earlier this week](/blog/2014/10/14/introducting-react-elements.html). If you haven't already, you should read up on the exciting changes in there!
+The biggest conceptual change we made in v0.12 is the move to React Elements. [We talked about this topic in depth earlier this week](/blog/2014/10/14/introducing-react-elements.html). If you haven't already, you should read up on the exciting changes in there!
 
 
 ## JSX Changes

Diff for: content/blog/2014-10-16-react-v0.12-rc1.md

@@ -67,7 +67,7 @@ Jay Garcia spent a lot of time during the beta working on a NES music player wit
 
 ## React Native with Babel and webpack
 
-React Native ships with a custom packager and custom ES6 transforms instead of using what the open source community settled on such as webpack and Babel. The main reason for this is performance – we couldn't get those tools to have sub-second reload time on a large codebase.
+React Native ships with a custom packager and custom ES6 transforms instead of using what the open source community settled on such as [webpack](https://webpack.js.org/) and [Babel](https://babeljs.io/). The main reason for this is performance – we couldn't get those tools to have sub-second reload time on a large codebase.
 
 Roman Liutikov found a way to [use webpack and Babel to run on React Native](https://github.com/roman01la/react-native-babel)! In the future, we want to work with those projects to provide cleaner extension mechanisms.
 

Diff for: content/blog/2015-03-30-community-roundup-26.md

@@ -7,7 +7,7 @@ This week, many people in the React community are at [ReactEurope](https://www.r
 
 With React 0.14, we're continuing to let React mature and to make minor changes as the APIs continue to settle down. I'll talk only about the two largest changes in this blog post; when we publish the final release we'll be sure to update all of our documentation and include a full changelog.
 
-You can install the new beta with `npm install [email protected]` and `npm install [email protected]`. As mentioned in [Deprecating react-tools](https://reactjs.org/blog/2015/06/12/deprecating-jstransform-and-react-tools.html), we're no longer updating the react-tools package so this release doesn't include a new version of it. Please try the new version out and let us know what you think, and please do file issues on our GitHub repo if you run into any problems.
+You can install the new beta with `npm install [email protected]` and `npm install [email protected]`. As mentioned in [Deprecating react-tools](/blog/2015/06/12/deprecating-jstransform-and-react-tools.html), we're no longer updating the react-tools package so this release doesn't include a new version of it. Please try the new version out and let us know what you think, and please do file issues on our GitHub repo if you run into any problems.
 
 ## Two Packages
 

Diff for: content/blog/2015-07-03-react-v0.14-beta-1.md

@@ -43,7 +43,7 @@ If you use ES6 promises, you may need to wrap your promise in order to make it c
 
 ```js
 const cancelablePromise = makeCancelable(
-  new Promise(r => component.setState({...}}))
+  new Promise(r => component.setState({...}))
 );
 
 cancelablePromise

Diff for: content/blog/2015-12-16-ismounted-antipattern.md

@@ -63,7 +63,7 @@ jscodeshift -t react-codemod/transforms/React-PropTypes-to-prop-types.js <path>
 
 The `propTypes`, `contextTypes`, and `childContextTypes` APIs will work exactly as before. The only change is that the built-in validators now live in a separate package.
 
-You may also consider using [Flow](https://flow.org/) to statically type check your JavaScript code, including [React components](https://flow.org/en/docs/frameworks/react/#setup-flow-with-react-a-classtoc-idtoc-setup-flow-with-react-hreftoc-setup-flow-with-reacta).
+You may also consider using [Flow](https://flow.org/) to statically type check your JavaScript code, including [React components](https://flow.org/en/docs/react/components/).
 
 ### Migrating from React.createClass
 
@@ -113,8 +113,8 @@ We're discontinuing active maintenance of React Addons packages. In truth, most
 - **react-addons-create-fragment** – React 16 will have first-class support for fragments, at which point this package won't be necessary. We recommend using arrays of keyed elements instead.
 - **react-addons-css-transition-group** - Use [react-transition-group/CSSTransitionGroup](https://github.com/reactjs/react-transition-group) instead. Version 1.1.1 provides a drop-in replacement.
 - **react-addons-linked-state-mixin** - Explicitly set the `value` and `onChange` handler instead.
-- **react-addons-pure-render-mixin** - Use [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
-- **react-addons-shallow-compare** - Use [`React.PureComponent`](/docs/react-api.html#react.purecomponent) instead.
+- **react-addons-pure-render-mixin** - Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
+- **react-addons-shallow-compare** - Use [`React.PureComponent`](/docs/react-api.html#reactpurecomponent) instead.
 - **react-addons-transition-group** - Use [react-transition-group/TransitionGroup](https://github.com/reactjs/react-transition-group) instead. Version 1.1.1 provides a drop-in replacement.
 - **react-addons-update** - Use [immutability-helper](https://github.com/kolodny/immutability-helper) instead, a drop-in replacement.
 - **react-linked-input** - Explicitly set the `value` and `onChange` handler instead.

Diff for: content/blog/2017-04-07-react-v15.5.0.md

@@ -163,7 +163,7 @@ Below is a detailed list of them.
     ```
 
     React 15: Converts `NaN`s to strings and passes them through.  
-    React 16: Warns and ignores them.
+    React 16: Converts `NaN`s to strings and passes them through with a warning.
 
 While testing this release, we have also [created an automatically generated table](https://github.com/facebook/react/blob/master/fixtures/attribute-behavior/AttributeTableSnapshot.md) for all known attributes to track potential regressions.