Improve npm run eject description

CHANGELOG.md

@@ -1,3 +1,150 @@
+## 0.4.1 (September 3, 2016)
+
+### Build Dependency (`react-scripts`)
+
+* We now support (but [don’t recommend](https://github.com/facebookincubator/create-react-app/issues/87#issuecomment-234627904)) `.jsx` file extension. ([@tizmagik](https://github.com/tizmagik) in [#563](https://github.com/facebookincubator/create-react-app/pull/563))
+* Proxy request errors are now printed to the console. ([@cloudmu](https://github.com/cloudmu) in [#502](https://github.com/facebookincubator/create-react-app/pull/502))
+
+### Migrating from 0.4.0 to 0.4.1
+
+Inside any created project that has not been ejected, run:
+
+```
+npm install --save-dev --save-exact [email protected]
+```
+
+## 0.4.0 (September 2, 2016)
+
+### Build Dependency (`react-scripts`)
+
+* **Breaking Change:** Disabled implicit serving of source files in development. ([@gaearon](https://github.com/gaearon) in [#551](https://github.com/facebookincubator/create-react-app/pull/551))
+* You can use `NODE_PATH` environment variable for absolute `import` paths. ([@jimmyhmiller](https://github.com/jimmyhmiller) in [#476](https://github.com/facebookincubator/create-react-app/pull/476))
+* If `src/setupTests.js` exists, it will be used to setup the test environment. ([@gaelduplessix](https://github.com/gaelduplessix) in [#548](https://github.com/facebookincubator/create-react-app/pull/548))
+* If `HTTPS` environment variable is set to `true`, development server will run in HTTPS mode. ([@dceddia](https://github.com/dceddia) in [#552](https://github.com/facebookincubator/create-react-app/pull/552))
+
+### Migrating from 0.3.1 to 0.4.0
+
+Inside any created project that has not been ejected, run:
+
+```
+npm install --save-dev --save-exact [email protected]
+```
+
+### Breaking Change in 0.4.0
+
+Paths like `/src/somefile.png` used to be served in development, but only by accident. They never worked in production builds. Since 0.4.0, we [don’t serve static files by default in development anymore either](https://github.com/facebookincubator/create-react-app/pull/551). This removes a dangerous inconsistency that we never intentionally supported.
+
+If you need a static file to be part for the build, [import it from JavaScript and you will get its filename](https://github.com/facebookincubator/create-react-app/blob/master/template/README.md#adding-images-and-fonts). This ensures it gets included into the production build as well, and its filename contains the content hash.
+
+If you used static files with `<link href>`, [read this new guide](https://github.com/facebookincubator/create-react-app/blob/master/template/README.md#referring-to-static-assets-from-link-href) on how to make sure these files get included into the builds. For example, you can replace `<link href="/src/favicons/favicon-32.png">` with `<link href="./src/favicons/favicon-32.png">`, and then Webpack will recognize it and include it into the build.
+
+If you referenced some other files from `index.html`, please file an issue to discuss your use case. In the meantime, you can serve them from a separate static server until your use case is supported.
+
+## 0.3.1 (September 2, 2016)
+
+### Build Dependency (`react-scripts`)
+
+* Bumps Jest dependency to fix a few issues discovered yesterday. ([@cpojer](https://github.com/cpojer) in [facebook/jest#1580](https://github.com/facebook/jest/pull/1580), [@insin](https://github.com/insin) in [facebook/jest#1574](https://github.com/facebook/jest/pull/1574))
+
+### Migrating from 0.3.0 to 0.3.1
+
+Inside any created project that has not been ejected, run:
+
+```
+npm install --save-dev --save-exact [email protected]
+```
+
+## 0.3.0 (September 1, 2016)
+
+### Build Dependency (`react-scripts`)
+
+* Testing is [now supported](https://github.com/facebookincubator/create-react-app/blob/master/template/README.md#running-tests)! ([Jest project contributors](https://github.com/facebook/jest/pulls?q=is%3Apr+is%3Aclosed), [@cpojer](https://github.com/cpojer) in [#250](https://github.com/facebookincubator/create-react-app/pull/250), [@gaearon](https://github.com/gaearon) in [#378](https://github.com/facebookincubator/create-react-app/pull/378), [#530](https://github.com/facebookincubator/create-react-app/pull/530), [#533](https://github.com/facebookincubator/create-react-app/pull/533))
+* Static files such as CSS, images, and fonts, can now exist outside `src` directory. ([@fson](https://github.com/fson) in [#504](https://github.com/facebookincubator/create-react-app/pull/504))
+* **Breaking Change:** Local paths in `<link href>` in `index.html` will now be correctly resolved, so deleting `favicon.ico` is not an error anymore. ([@andreypopp](https://github.com/andreypopp) in [#428](https://github.com/facebookincubator/create-react-app/pull/428))
+* Removed an annoying lint rule that warned for `<div ref={node => this.node = node}>`. ([@mrscobbler](https://github.com/mrscobbler) in [#529](https://github.com/facebookincubator/create-react-app/pull/529))
+* Temporarily disabled `react-constant-elements` Babel transform because of its bugs. ([@gaearon](https://github.com/gaearon) in [#534](https://github.com/facebookincubator/create-react-app/pull/534))
+* Fixed a permission issue with Docker. ([@gaearon](https://github.com/gaearon) in [73c940](https://github.com/facebookincubator/create-react-app/commit/73c940a73205d761230f8d6bf81ecfd460ba28a9))
+* Fixed an issue with generator syntax in Jest that occurred in an alpha release. ([@gaearon](https://github.com/gaearon) in [#535](https://github.com/facebookincubator/create-react-app/pull/535))
+
+### Global CLI (`create-react-app`)
+
+* You can now create a project in a folder that already contains an `.idea` folder, which is necessary for future WebStorm integration. ([@denofevil](https://github.com/denofevil) in [#522](https://github.com/facebookincubator/create-react-app/pull/522))
+
+### Migrating from 0.2.3 to 0.3.0
+
+You may optionally update the global command (it’s not required):
+
+```
+npm install -g [email protected]
+```
+
+Inside any created project that has not been ejected, run:
+
+```
+npm install --save-dev --save-exact [email protected]
+```
+
+#### Breaking Change
+
+Now `favicon.ico` is not treated specially anymore.  
+If you use it, move it to `src` and add the following line to `<head>` in your HTML:
+
+```html
+<link rel="shortcut icon" href="./src/favicon.ico">
+```
+
+#### New Feature
+
+Since 0.3.0 added a test runner, we recommend that you add it to the `scripts` section of your `package.json` like this:
+
+```js
+  // ...
+  "scripts": {
+    // ...
+    "test": "react-scripts test --env=jsdom"
+  }
+```
+
+[Then read the testing guide to learn more about using it!](https://github.com/facebookincubator/create-react-app/blob/master/template/README.md#running-tests)
+
+## 0.2.3 (August 25, 2016)
+
+### Build Dependency (`react-scripts`)
+
+* You can now [proxy requests to an API server](https://github.com/facebookincubator/create-react-app/blob/ef94b0561d5afb9b50b905fa5cd3f94e965c69c0/template/README.md#proxying-api-requests-in-development) without worrying about CORS. ([@gaearon](https://github.com/gaearon) in [#282](https://github.com/facebookincubator/create-react-app/pull/282))
+* You can now [pass custom environment variables](https://github.com/facebookincubator/create-react-app/blob/ef94b0561d5afb9b50b905fa5cd3f94e965c69c0/template/README.md#adding-custom-environment-variables) to your application. ([@eliperelman](https://github.com/eliperelman) in [#342](https://github.com/facebookincubator/create-react-app/pull/342))
+* You can now [use `async` and `await`](https://ponyfoo.com/articles/understanding-javascript-async-await) syntax. ([@gaearon](https://github.com/gaearon) in [#327](https://github.com/facebookincubator/create-react-app/pull/327), [@fson](https://github.com/fson) in [#332](https://github.com/facebookincubator/create-react-app/pull/332))
+* Paths with period in them now load successfully on the development server. ([@mxstbr](https://github.com/mxstbr) in [#422](https://github.com/facebookincubator/create-react-app/pull/422))
+* Images with `.webp` extension are now supported. ([@gafemoyano](https://github.com/gafemoyano) in [#458](https://github.com/facebookincubator/create-react-app/pull/458))
+* The most recent version of React is now added to `package.json`. ([@wdhorton](https://github.com/wdhorton) in [#477](https://github.com/facebookincubator/create-react-app/pull/477))
+* Babel configuration is simplified. ([@kripod](https://github.com/kripod) in [#490](https://github.com/facebookincubator/create-react-app/pull/490))
+
+### Migrating from 0.2.2 to 0.2.3
+
+Update `react-scripts` to point to `0.2.3` in your `package.json` and run `npm install`. You shouldn’t need to do anything else.
+
+Newly created projects will use `0.2.3` automatically. You **don’t** need to update the global `create-react-app` CLI itself. It stays at `0.2.0` for now because it doesn’t have any changes.
+
+## 0.2.2 (August 22, 2016)
+
+### Build Dependency (`react-scripts`)
+
+* When the bundle size changes, we now display the difference after build. ([@elijahmanor](https://github.com/elijahmanor) in [#340](https://github.com/facebookincubator/create-react-app/pull/340))
+* `npm install`ing a missing dependency now forces a rebuild. ([@gaearon](https://github.com/gaearon) in [#349](https://github.com/facebookincubator/create-react-app/pull/349))
+* Autoprefixer config now includes more commonly supported browsers. ([@kripod](https://github.com/kripod) in [#345](https://github.com/facebookincubator/create-react-app/pull/345))
+* All the configuration is now documented inline so ejecting doesn’t leave you in the dark. ([@gaearon](https://github.com/gaearon) in [#362](https://github.com/facebookincubator/create-react-app/pull/362))
+* `Object.assign()` polyfill is now bundled by default. ([@gaearon](https://github.com/gaearon) in [#399](https://github.com/facebookincubator/create-react-app/pull/399))
+* [React Native Web](https://www.smashingmagazine.com/2016/08/a-glimpse-into-the-future-with-react-native-for-web/) now works out of the box. ([@grigio](https://github.com/grigio) in [#407](https://github.com/facebookincubator/create-react-app/pull/407))
+* Same asset filenames in different folders don’t confuse the server now. ([@arunoda](https://github.com/arunoda) in [#446](https://github.com/facebookincubator/create-react-app/pull/446))
+* The `otf` font format is now supported. ([@A-gambit](https://github.com/A-gambit) in [#434](https://github.com/facebookincubator/create-react-app/pull/434))
+* The `new-cap` linting rule has been disabled thanks to feedback from Immutable.js users. ([@rricard](https://github.com/rricard) in [#470](https://github.com/facebookincubator/create-react-app/pull/470))
+
+### Migrating from 0.2.1 to 0.2.2
+
+Update `react-scripts` to point to `0.2.2` in your `package.json` and run `npm install`. You shouldn’t need to do anything else.
+
+Newly created projects will use `0.2.2` automatically. You **don’t** need to update the global `create-react-app` CLI itself. It stays at `0.2.0` for now because it doesn’t have any changes.
+
 ## 0.2.1 (August 1, 2016)
 
 ### Build Dependency (`react-scripts`)

CONTRIBUTING.md

@@ -1,34 +1,53 @@
-# Contributing to `create-react-app`
+# Contributing to Create React App
 
-♥ `create-react-app` and want to get involved? Thanks! There are plenty of ways you can help!
+Loving Create React App and want to get involved? Thanks! There are plenty of ways you can help.
 
 Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.
 
 Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and features.
 
-## Core ideas
+## Core Ideas
 
-We do not want any flags or configuration, that would defeat the purpose of this tool. We want to find good defaults and actively find ways to improve the developer experience.
+As much as possible, we try to avoid adding configuration and flags. The purpose of this tool is to provide the best experience for people getting started with React, and this will always be our first priority. This means that sometimes we [sacrifice additional functionality](https://gettingreal.37signals.com/ch05_Half_Not_Half_Assed.php) (such as server rendering) because it is too hard to solve it in a way that wouldn’t require any configuration.
 
-We try not to make any controversial choices. If the community is split between different tools, we won't just pick the least controversial or most popular, the tool itself should be agnostic between them.
+We prefer **convention, heuristics, or interactivity** over configuration.  
+Here’s a few examples of them in action.
 
-*These ideas are subject to change at any time*
+### Convention
+
+Instead of letting the user specify the entry filename, we always assume it to be `src/index.js`. Rather than letting the user specify the output bundle name, we generate it, but make sure to include the content hash in it. Whenever possible, we want to leverage convention to make good choices for the user, especially in cases where it’s easy to misconfigure something.
+
+### Heuristics
+
+Normally, `npm start` runs on port `3000`, and this is not explicitly configurable. However some environments like cloud IDEs want the programs to run on a specific port to serve their output. We want to play well with different environments, so Create React App reads `PORT` environment variable and prefers it when it is specified. The trick is that we know cloud IDEs already specify it automatically so there is no need for the user to do anything. Create React App relies on heuristics to do the right thing depending on environment.
+
+Another example of this is how `npm test` normally launches the watcher, but if the `CI` environment variable is set, it will run tests once. We know that popular CI environments set this variable so the user doesn’t need to do anything. It just works.
+
+### Interactivity
+
+We prefer to add interactivity to the command line interface rather than add configuration flags. For example, `npm start` will attempt to run with port `3000` by default but it may be busy. Many other tools just fail in this case and ask that you pass a different port, but Create React App will display a prompt asking if you’d like to run the app on the next available port.
+
+Another example of interactivity is `npm test` watcher interface. Instead of asking people to pass command line flags for switching between test runner modes or search patterns, we print a hint with keys that you can press during the test session to instruct watcher what to do. Jest supports both flags and interactive CLI but Create React App prefers long-running sessions to keep user immersed in the flow over short-running sessions with different flags.
+
+### Breaking the Rules
+
+No rules are perfect. Sometimes we may introduce flags or configuration if we believe the value is high enough to justify the mental cost. For example, we know that apps may be hosted paths different from the root, and we need to support this use case. However we still try to fall back to heuristics when possible. In this example, we ask that you specify `homepage` in `package.json`, and infer the correct path based on it. We also nudge the user to fill out the `homepage` after the build so the user becomes aware that the feature exists.
 
 ## Submitting a Pull Request
 
-Good pull requests - patches, improvements, new features - are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
+Good pull requests, such as patches, improvements, and new features, are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.
 
-Please **ask first** if somebody else is already working on this or the core developers think your feature is in-scope for `create-react-app`. Generally always have a related issue with discussions for whatever you are including.
+Please **ask first** if somebody else is already working on this or the core developers think your feature is in-scope for Create React App. Generally always have a related issue with discussions for whatever you are including.
 
-Please also provide a **test plan**, i.e. specify how you verified what you added works.
+Please also provide a **test plan**, i.e. specify how you verified that your addition works.
 
-## Setting up a local copy of the repository
+## Setting Up a Local Copy
 
 1. Clone the repo with `git clone https://github.com/facebookincubator/create-react-app`
 
 2. Run `npm install` in the root `create-react-app` folder **and** the `create-react-app/global-cli` folder
 
-Once it is done, you can modify any file locally and run `npm start` or `npm run build` just like in a generated project.
+Once it is done, you can modify any file locally and run `npm start`, `npm test` or `npm run build` just like in a generated project.
 
 If you want to try out the end-to-end flow with the global CLI, you can do this too:
 
@@ -39,4 +58,21 @@ cd my-app
 
 and then run `npm start` or `npm run build`.
 
+## Cutting a Release
+
+1. Tag all merged PRs that go into the release with the relevant milestone.
+2. Close the milestone.
+3. In most releases, only `react-scripts` needs to be released. If you don’t have any changes to the `global-cli` folder, you don’t need to bump its version or publish it.
+4. Note that files in `global-cli` should be modified with extreme caution. Since it’s a global CLI, any version of `create-react-app` (global CLI) including very old ones should work with the latest version of `react-scripts`.
+5. Add an entry to `CHANGELOG.md` detailing what has changed with links to PRs and their authors. Use previous entries for inspiration. Group changes to `react-scripts` and `create-react-app` separately in the notes, for example like in `0.2.0` release notes.
+6. Make sure to include “Migrating from ...” instructions for the previous release. Often you can copy and paste them.
+7. After merging the changelog update, create a GitHub Release with the same text. See previous Releases for inspiration.
+8. If you are releasing updates to the `create-react-app` CLI (likely not), go to `global-cli`, bump the version in `package.json` and run `npm publish` in that folder.
+9. If you are releasing updates to `react-scripts` (most likely!), bump the version in `package.json`. **Do not run `npm publish`. Instead, run `sh tasks/release.sh`.**
+10. Wait for a long time, and it will get published. Don’t worry that it’s stuck. It will bundle dependencies into a single tarball before publishing for faster installs.
+
+Make sure to test the released version! If you want to be extra careful, you can publish a prerelease by running `sh tasks/release.sh --tag next` instead of `sh tasks/release.sh`.
+
+------------
+
 *Many thanks to [h5bp](https://github.com/h5bp/html5-boilerplate/blob/master/CONTRIBUTING.md) for the inspiration with this contributing guide*