diff --git a/.travis.yml b/.travis.yml index 8ecb5b8661..e2a9f72e12 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,8 +1,11 @@ --- +sudo: required +dist: trusty language: node_js node_js: - 4 -sudo: false +rvm: +- 2.2.3 cache: directories: - docs/vendor/bundle diff --git a/CHANGELOG.md b/CHANGELOG.md index d92bedab35..75c1ed8b37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,34 @@ +## 15.3.0 (July 29, 2016) + +### React +- Add `React.PureComponent` - a new base class to extend, replacing `react-addons-pure-render-mixin` now that mixins don't work with ES2015 classes. ([@spicyj](https://github.com/spicyj) in [#7195](https://github.com/facebook/react/pull/7195)) +- Add new warning when modifying `this.props.children`. ([@jimfb](https://github.com/jimfb) in [#7001](https://github.com/facebook/react/pull/7001)) +- Fixed issue with ref resolution order. ([@gaearon](https://github.com/gaearon) in [#7101](https://github.com/facebook/react/pull/7101)) +- Warn when mixin is undefined. ([@swaroopsm](https://github.com/swaroopsm) in [#6158](https://github.com/facebook/react/pull/6158)) +- Downgrade "unexpected batch number" invariant to a warning. ([@spicyj](https://github.com/spicyj) in [#7133](https://github.com/facebook/react/pull/7133)) +- Validate arguments to `oneOf` and `oneOfType` PropTypes sooner. ([@troydemonbreun](https://github.com/troydemonbreun) in [#6316](https://github.com/facebook/react/pull/6316)) +- Warn when calling PropTypes directly. ([@Aweary](https://github.com/Aweary) in [#7132](https://github.com/facebook/react/pull/7132), [#7194](https://github.com/facebook/react/pull/7194)) +- Improve warning when using Maps as children. ([@keyanzhang](https://github.com/keyanzhang) in [#7260](https://github.com/facebook/react/pull/7260)) +- Add additional type information to the `PropTypes.element` warning. ([@alexzherdev](https://github.com/alexzherdev) in [#7319](https://github.com/facebook/react/pull/7319)) +- Improve component identification in no-op `setState` warning. ([@keyanzhang](https://github.com/keyanzhang) in [#7326](https://github.com/facebook/react/pull/7326)) + +### React DOM +- Fix issue with nested server rendering. ([@Aweary](https://github.com/Aweary) in [#7033](https://github.com/facebook/react/pull/7033)) +- Add `xmlns`, `xmlnsXlink` to supported SVG attributes. ([@salzhrani](https://github.com/salzhrani) in [#6471](https://github.com/facebook/react/pull/6471)) +- Add `referrerPolicy` to supported HTML attributes. ([@Aweary](https://github.com/Aweary) in [#7274](https://github.com/facebook/react/pull/7274)) +- Fix issue resulting in `` initial value being rounded. ([@troydemonbreun](https://github.com/troydemonbreun) in [#7251](https://github.com/facebook/react/pull/7251)) + +### React Test Renderer +- Initial public release of package allowing more focused testing. Install with `npm install react-test-renderer`. ([@spicyj](https://github.com/spicyj) in [#6944](https://github.com/facebook/react/pull/6944), [#7258](https://github.com/facebook/react/pull/7258), [@iamdustan](https://github.com/iamdustan) in [#7362](https://github.com/facebook/react/pull/7362)) + +### React Perf Add-on +- Fix issue resulting in excessive warnings when encountering an internal measurement error. ([@sassanh](https://github.com/sassanh) in [#7299](https://github.com/facebook/react/pull/7299)) + +### React TestUtils Add-on +- Implement `type` property on for events created via `TestUtils.Simulate.*`. ([@yaycmyk](https://github.com/yaycmyk) in [#6154](https://github.com/facebook/react/pull/6154)) +- Fix crash when running TestUtils with the production build of React. ([@gaearon](https://github.com/gaearon) in [#7246](https://github.com/facebook/react/pull/7246)) + + ## 15.2.1 (July 8, 2016) ### React diff --git a/README.md b/README.md index e26c89bfe6..6d618ff784 100644 --- a/README.md +++ b/README.md @@ -31,16 +31,16 @@ You'll notice that we used an HTML-like syntax; [we call it JSX](https://faceboo ## Installation -The fastest way to get started is to serve JavaScript from the CDN (also available on [cdnjs](https://cdnjs.com/libraries/react) and [jsdelivr](https://www.jsdelivr.com/projects/react)): +The fastest way to get started is to serve JavaScript from a CDN. We're using [npmcdn](https://npmcdn.com/) below but React is also available on [cdnjs](https://cdnjs.com/libraries/react) and [jsdelivr](https://www.jsdelivr.com/projects/react): ```html - + - + ``` -We've also built a [starter kit](https://facebook.github.io/react/downloads/react-15.2.1.zip) which might be useful if this is your first time using React. It includes a webpage with an example of using React with live code. +We've also built a [starter kit](https://facebook.github.io/react/downloads/react-15.3.0.zip) which might be useful if this is your first time using React. It includes a webpage with an example of using React with live code. If you'd like to use [bower](http://bower.io), it's as easy as: diff --git a/docs/404.md b/docs/404.md index 6d4039fb3d..ab9ba1d60c 100644 --- a/docs/404.md +++ b/docs/404.md @@ -1,6 +1,7 @@ --- layout: single title: Page Not Found +permalink: 404.html --- We couldn't find what you were looking for. diff --git a/docs/Gemfile b/docs/Gemfile index 4f4991e3b2..f144584eff 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -3,11 +3,12 @@ source 'https://rubygems.org' gem 'rake' # jekyll, which builds it all -# 2.0 includes sass processing -gem 'jekyll', '~>2.0' +# 3.0 includes sass processing +gem 'jekyll', '~>3.1' -# Auto redirect pages +# Jekyll extensions gem 'jekyll-redirect-from' +gem 'jekyll-paginate' # JSON gem 'json' @@ -17,3 +18,12 @@ gem 'rb-fsevent' # For markdown header cleanup gem 'sanitize', '~>2.0' + +# Markdown +gem 'redcarpet' + +# Syntax highlighting +gem 'pygments.rb' + +# Avoid having to poll for changes on Windows +gem 'wdm', '>= 0.1.0' if Gem.win_platform? \ No newline at end of file diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 89a0f264aa..bd77546562 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -1,85 +1,70 @@ GEM remote: https://rubygems.org/ specs: - blankslate (2.1.2.4) - celluloid (0.15.2) - timers (~> 1.1.0) - classifier (1.3.4) - fast-stemmer (>= 1.0.0) - coffee-script (2.3.0) - coffee-script-source - execjs - coffee-script-source (1.7.1) colorator (0.1) - execjs (2.2.1) - fast-stemmer (1.0.2) - ffi (1.9.3) - jekyll (2.2.0) - classifier (~> 1.3) + ffi (1.9.14) + ffi (1.9.14-x64-mingw32) + jekyll (3.1.6) colorator (~> 0.1) - jekyll-coffeescript (~> 1.0) - jekyll-gist (~> 1.0) - jekyll-paginate (~> 1.0) jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 1.0) + jekyll-watch (~> 1.1) kramdown (~> 1.3) - liquid (~> 2.6.1) + liquid (~> 3.0) mercenary (~> 0.3.3) - pygments.rb (~> 0.6.0) - redcarpet (~> 3.1) + rouge (~> 1.7) safe_yaml (~> 1.0) - toml (~> 0.1.0) - jekyll-coffeescript (1.0.0) - coffee-script (~> 2.2) - jekyll-gist (1.1.0) - jekyll-paginate (1.0.0) - jekyll-redirect-from (0.5.0) - jekyll (~> 2.0) - jekyll-sass-converter (1.2.0) - sass (~> 3.2) - jekyll-watch (1.1.0) - listen (~> 2.7) - json (1.8.1) - kramdown (1.4.1) - liquid (2.6.1) - listen (2.7.9) - celluloid (>= 0.15.2) - rb-fsevent (>= 0.9.3) - rb-inotify (>= 0.9) - mercenary (0.3.4) - mini_portile (0.6.0) - nokogiri (1.6.3.1) - mini_portile (= 0.6.0) - parslet (1.5.0) - blankslate (~> 2.0) - posix-spawn (0.3.9) - pygments.rb (0.6.0) + jekyll-paginate (1.1.0) + jekyll-redirect-from (0.11.0) + jekyll (>= 2.0) + jekyll-sass-converter (1.4.0) + sass (~> 3.4) + jekyll-watch (1.4.0) + listen (~> 3.0, < 3.1) + json (2.0.1) + kramdown (1.11.1) + liquid (3.0.6) + listen (3.0.8) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + mercenary (0.3.6) + mini_portile2 (2.1.0) + nokogiri (1.6.8) + mini_portile2 (~> 2.1.0) + pkg-config (~> 1.1.7) + nokogiri (1.6.8-x64-mingw32) + mini_portile2 (~> 2.1.0) + pkg-config (~> 1.1.7) + pkg-config (1.1.7) + posix-spawn (0.3.11) + pygments.rb (0.6.3) posix-spawn (~> 0.3.6) - yajl-ruby (~> 1.1.0) - rake (10.3.2) - rb-fsevent (0.9.4) - rb-inotify (0.9.5) + yajl-ruby (~> 1.2.0) + rake (11.2.2) + rb-fsevent (0.9.7) + rb-inotify (0.9.7) ffi (>= 0.5.0) - redcarpet (3.1.2) + redcarpet (3.3.4) + rouge (1.11.1) safe_yaml (1.0.4) - sanitize (2.0.6) + sanitize (2.1.0) nokogiri (>= 1.4.4) - sass (3.3.14) - timers (1.1.0) - toml (0.1.1) - parslet (~> 1.5.0) - yajl-ruby (1.1.0) + sass (3.4.22) + yajl-ruby (1.2.1) PLATFORMS ruby + x64-mingw32 DEPENDENCIES - jekyll (~> 2.0) + jekyll (~> 3.1) + jekyll-paginate jekyll-redirect-from json + pygments.rb rake rb-fsevent + redcarpet sanitize (~> 2.0) BUNDLED WITH - 1.10.1 + 1.11.2 diff --git a/docs/_config.yml b/docs/_config.yml index a4bdbce138..1c85394736 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,21 +5,37 @@ url: https://facebook.github.io baseurl: "/react" permalink: "/blog/:year/:month/:day/:title.html" paginate_path: "/blog/page:num/" -relative_permalinks: true paginate: 5 timezone: America/Los_Angeles highlighter: pygments defaults: - scope: path: '' - type: post + type: posts values: layout: post + sectionid: blog +- scope: + path: blog + type: pages + values: + sectionid: blog - scope: path: docs - type: page + type: pages values: layout: docs + sectionid: docs +- scope: + path: tips + type: pages + values: + sectionid: docs +- scope: + path: contributing + type: pages + values: + sectionid: docs exclude: - Gemfile - Gemfile.lock @@ -36,13 +52,14 @@ sass: sass_dir: _css gems: - jekyll-redirect-from -react_version: 15.2.1 +- jekyll-paginate +react_version: 15.3.0 react_hashes: - dev: g2900ZIpFKhyIsz+bnx4YDEfAISugYRU58ljeAgI8TZ0A0AkRLGUCN7OmjF16Cj+ - prod: ICzDcvbNpMy31akJ8WzksHoK9tl1iRIUPRCaBRN+sn/k40TNGjs9IvgPN0SekkDT - addons_dev: js+Yc2Nd259A4+UPokRNVOXJdipY9oIrkkDdFJAZzZxgryRJLkWYDrJVgM97aweF - addons_prod: DaNE8gIDQr8RWDoa4y9HX/70fzdOBzpV/e+7RJtMN1MnXEiCMpiIFtutJml6mvPC - dom_dev: LD1cH7LXOdrrq5dOOiE2N/HdgCyrw3nmUMq6oPFCJKUfWO3i7AozvBKz7G3maMHt - dom_prod: 1dLXeik7kFcDPXbz3rX9dibLTGh/D8dpAOL5X2Ml09pH8wpQlpL+JOgOnzAMCO4T - dom_server_dev: WJt1y2JljJEQ1OgpupP2ly0GgIwi7Aodp+n+/fv2bakpgWpXMnLklj5rSouRJt59 - dom_server_prod: Y6UDASOvQhWWBwXy/Ccp4vSAt0YAp+ymuRXBX4hffy+pMlOgjXzryIjbiceIB6GF + dev: R8v794QN9hrNjnivoQ3Mf7nMGVwFIHBkUmBanB40ZBIMttZbBEUatXNosjytvPUC + prod: asiNTW+3f/iCKtm+05EX+4V4n6R5R1fyAY9M8Md0DLHodFResXMSBlt8ns9iJaPK + addons_dev: iR3HmJX+5siYwRvy6ZXWWN/dNP4IuItUsfk0JJmwxaBIYtWHZhK/2N7wrAcxmpS8 + addons_prod: A/63GcxBS05SAxTWB0+wQKyQl8RVEH3nOuBuxwg/WV6yI5qpfEy4ksn90bqJdFJY + dom_dev: PKr8yTHUBD0chzmoJ6ZYtB1nB87GTEWPmuDlDV7iARDrYGki2fmVB0ae3vf3LX0O + dom_prod: TBEslZF7tpwiuBgt/ajgWUKvDGuCExkmEoWygscHE/OOajWS24BLAaf2/z7lj/9n + dom_server_dev: UxEqwIE5+BLQKOqKHnPfJBOrSDo7HyocIl6sTb6taLayrVmDuhQ5VM4iauS54BbK + dom_server_prod: hOLRkO2HGPRi0d73qKZWueHZyDD/6BID0CJax9kNUNaAvMR4atbNIcYfk2BoM8T3 diff --git a/docs/_data/nav_contributing.yml b/docs/_data/nav_contributing.yml new file mode 100644 index 0000000000..b1dcc5c80b --- /dev/null +++ b/docs/_data/nav_contributing.yml @@ -0,0 +1,4 @@ +- title: Contributing + items: + - id: design-principles + title: Design Principles diff --git a/docs/_includes/nav_docs.html b/docs/_includes/nav_docs.html index b3e8a277f5..560170606d 100644 --- a/docs/_includes/nav_docs.html +++ b/docs/_includes/nav_docs.html @@ -35,4 +35,18 @@ {% endfor %} + + + {% for section in site.data.nav_contributing %} +
+ + +This doesn’t mean those tools aren’t great. To many of us, they have become indispensable, and we very much appreciate the effort of their maintainers. They already have too much on their plates to worry about the state of the React ecosystem. + +Still, we knew it was frustrating to spend days setting up a project when all you wanted was to learn React. We wanted to fix this. + +## Could We Fix This? + +We found ourselves in an unusual dilemma. + +So far, [our strategy](/react/contributing/design-principles.html#dogfooding) has been to only release the code that we are using at Facebook. This helped us ensure that every project is battle-tested and has clearly defined scope and priorities. + +However, tooling at Facebook is different than at many smaller companies. Linting, transpilation, and packaging are all handled by powerful remote development servers, and product engineers don’t need to configure them. While we wish we could give a dedicated server to every user of React, even Facebook cannot scale that well! + +The React community is very important to us. We knew that we couldn’t fix the problem within the limits of our open source philosophy. This is why we decided to make an exception, and to ship something that we didn’t use ourselves, but that we thought would be useful to the community. + +## The Quest for a React CLI + +Having just attended [EmberCamp](http://embercamp.com/) a week ago, I was excited about [Ember CLI](https://ember-cli.com/). Ember users have a great “getting started” experience thanks to a curated set of tools united under a single command-line interface. I have heard similar feedback about [Elm Reactor](https://github.com/elm-lang/elm-reactor). + +Providing a cohesive curated experience is valuable by itself, even if the user could in theory assemble those parts themselves. Kathy Sierra [explains it best](http://seriouspony.com/blog/2013/7/24/your-app-makes-me-fat): + +>If your UX asks the user to make *choices*, for example, even if those choices are both clear and useful, the act of *deciding* is a cognitive drain. And not just *while* they’re deciding... even *after* we choose, an unconscious cognitive background thread is slowly consuming/leaking resources, “Was *that* the right choice?” + +I never tried to write a command-line tool for React apps, and neither has [Christopher](https://twitter.com/vjeux). We were chatting on Messenger about this idea, and we decided to work together on it for a week as a hackathon project. + +We knew that such projects traditionally haven’t been very successful in the React ecosystem. Christopher told me that multiple “React CLI” projects have started and failed at Facebook. The community tools with similar goals also exist, but so far they have not yet gained enough traction. + +Still, we decided it was worth another shot. Christopher and I created a very rough proof of concept on the weekend, and [Kevin](https://twitter.com/lacker) soon joined us. + +We invited some of the community members to collaborate with us, and we have spent this week working on this tool. We hope that you’ll enjoy using it! [Let us know what you think.](https://github.com/facebookincubator/create-react-app/issues/11) + +We would like to express our gratitude to [Max Stoiber](https://twitter.com/mxstbr), [Jonny Buchanan](https://twitter.com/jbscript), [Ean Platter](https://twitter.com/eanplatter), [Tyler McGinnis](https://github.com/tylermcginnis), [Kent C. Dodds](https://github.com/kentcdodds), and [Eric Clemmons](https://twitter.com/ericclemmons) for their early feedback, ideas, and contributions. diff --git a/docs/_posts/2016-08-05-relay-state-of-the-state.md b/docs/_posts/2016-08-05-relay-state-of-the-state.md new file mode 100644 index 0000000000..741d35c236 --- /dev/null +++ b/docs/_posts/2016-08-05-relay-state-of-the-state.md @@ -0,0 +1,81 @@ +--- +title: "Relay: State of the State" +author: josephsavona +--- + +This month marks a year since we released Relay and we'd like to share an update on the project and what's next. + +## A Year In Review + +A year after launch, we're incredibly excited to see an active community forming around Relay and that companies such as Twitter are [using Relay in production](https://fabric.io/blog/building-fabric-mission-control-with-graphql-and-relay): + +> For a project like mission control, GraphQL and Relay were a near-perfect solution, and the cost of building it any other way justified the investment. +> +> -- Fin Hopkins + +This kind of positive feedback is really encouraging (I'll admit to re-reading that post far too many times), and great motivation for us to keep going and make Relay even better. + +With the community's help we've already come a long way since the technical preview. Here are some highlights: + +- In March we added support for server-side rendering and for creating multiple instances of Relay on a single page. This was a coordinated effort over the course of several months by community members [Denis Nedelyaev](https://github.com/denvned) and [Gerald Monaco](https://github.com/devknoll) (now at Facebook). +- Also in March we added support for React Native. While we use Relay and React Native together internally, they didn't quite work together in open-source out of the box. We owe a big thanks to [Adam Miskiewicz](https://github.com/skevy), [Tom Burns](https://github.com/boourns), [Gaëtan Renaudeau](https://github.com/gre), [David Aurelio](https://github.com/davidaurelio), [Martín Bigio](https://github.com/martinbigio), [Paul O’Shannessy](https://github.com/zpao), [Ben Alpert](https://github.com/spicyj), and many others who helped track down and resolve issues. Finally, thanks to [Steven Luscher](https://github.com/steveluscher) for coordinating this effort and building the first Relay/ReactNative example app. + +We've also seen some great open-source projects spring up around Relay: + +- [Denis Nedelyaev](https://github.com/denvned) created [isomorphic-relay](https://github.com/denvned/isomorphic-relay/), a package that helps developers build server-rendered Relay apps where data is prepared on the server and then used to bootstrap the app on the client. +- [Jimmy Jia](https://github.com/taion) created [react-router-relay](https://github.com/relay-tools/react-router-relay) to integrate Relay data-fetching into React Router. +- [Pavel Chertorogov](https://github.com/nodkz) released [relay-network-layer](https://github.com/nodkz/react-relay-network-layer), which adds features such as batching query requests, middleware, authentication, logging, and more. + +This is just a small sampling of the community's contributions. So far we've merged over 300 PRs - about 25% of our commits - from over 80 of you. These PRs have improved everything from the website and docs down the very core of the framework. We're humbled by these outstanding contributions and excited to keep working with each of you! + +# Retrospective & Roadmap + +Earlier this year we paused to reflect on the state of the project. What was working well? What could be improved? What features should we add, and what could we remove? A few themes emerged: performance on mobile, developer experience, and empowering the community. + +## Mobile Perf + +First, Relay was built to serve the needs of product developers at Facebook. In 2016, that means helping developers to build apps that work well on [mobile devices connecting on slower networks](https://newsroom.fb.com/news/2015/10/news-feed-fyi-building-for-all-connectivity/). For example, people in developing markets commonly use [2011 year-class phones](https://code.facebook.com/posts/307478339448736/year-class-a-classification-system-for-android/) and connect via [2G class networks](https://code.facebook.com/posts/952628711437136/classes-performance-and-network-segmentation-on-android/). These scenarios present their own challenges. + +Therefore, one of our primary goals this year is to optimize Relay for performance on low-end mobile devices *first*, knowing that this can translate to improved performance on high-end devices as well. In addition to standard approaches such as benchmarking, profiling, and optimizations, we're also working on big-picture changes. + +For example, in today's Relay, here's what happens when an app is opened. First, React Native starts initializing the JavaScript context (loading and parsing your code and then running it). When this finishes, the app executes and Relay sees that you need data. It constructs and prints the query, uploads the query text to the server, processes the response, and renders your app. (Note that this process applies on the web, except that the code has to be *downloaded* instead of loaded from the device.) + +Ideally, though, we could begin fetching data as soon as the native code had loaded - in parallel with the JS context initialization. By the time your JS code was ready to run, the data-fetching would already be under way. To do this we would need a way to determine *statically* - at build time - what query an application would send. + +The key is that GraphQL is already static - we just need to fully embrace this fact. More on this later. + +## Developer Experience + +Next, we've paid attention to the community's feedback and know that, to put it simply, Relay could be "easier" to use (and "simpler" too). This isn't entirely surprising to us - Relay was originally designed as a routing library and gradually morphed into a data-fetching library. Concepts like Relay "routes", for example, no longer serve as critical a role and are just one more concept that developers have to learn about. Another example is mutations: while writes *are* inherently more complex than reads, our API doesn't make the simple things simple enough. + +Alongside our focus on mobile performance, we've also kept the developer experience in mind as we evolve Relay core. + +## Empowering the Community + +Finally, we want to make it easier for people in the community to develop useful libraries that work with Relay. By comparison, React's small surface area - components - allows developers to build cool things like routing, higher-order components, or reusable text editors. For Relay, this would mean having the framework provide core primitives that users can build upon. We want it to be possible for the community to integrate Relay with view libraries other than React, or to build real-time subscriptions as a complementary library. + +# What's Next + +These were big goals, and also a bit scary; we knew that incremental improvements would only allow us to move so fast. So in April we started a project to build a new implementation of Relay core targeting low-end mobile devices from the start. + +As you can guess since we're writing this, the experiment was a success. The result is a new core that retains the best parts of Relay today - colocated components & data-dependencies, automatic data/view consistency, declarative data-fetching - while improving performance on mobile devices and addressing several common areas of confusion. + +We're currently focused on shipping the first applications using the new core: ironing out bugs, refining the API changes and developer experience, and adding any missing features. We're excited to bring these changes to open source, and will do so once we've proven them in production. We'll go into more detail in some upcoming talks - links below - but for now here's an overview: + +- **Static Queries**: By adding a couple of Relay-specific directives, we've been able to retain the expressivity of current Relay queries using static syntax (concretely: you know what query an app will execute just by looking at the source text, without having to run that code). For starters this will allow Relay apps to start fetching data in parallel with JavaScript initialization. But it also unlocks other possibilities: knowing the query ahead of time means that we can generate optimized code for handling query responses, for example, or for reading query data from an offline cache. +- **Expressive Mutations**: We'll continue to support a higher-level mutation API for common cases, but will also provide a lower-level API that allows "raw" data access where necessary. If you need to order a list of cached elements, for example, there will be a way to `sort()` it. +- **Route-less Relay**: Routes will be gone in open source. Instead of a route with multiple query definitions, you'll just provide a single query with as many root fields as you want. +- **Cache Eviction/Garbage Collection**: The API and architecture is designed from the start to allow removing cached data that is no longer referenced by a mounted view. + +Stepping back, we recognize that any API changes will require an investment on your part. To make the transition easier, though, *we will continue to support the current API for the foreseeable future* (we're still using it too). And as much as possible we will open-source the tools that we use to migrate our own code. Ideas that we're exploring include codemods, an interoperability layer for the old/new APIs, and tutorials & guides to ease migration. + +Ultimately, we're making these changes because we believe they make Relay better all around: simpler for developers building apps and faster for the people using them. + +# Conclusion + +If you made it this far, congrats and thanks for reading! We'll be sharing more information about these changes in some upcoming talks: + +- [Greg Hurrell](https://github.com/wincent) will presenting a Relay "Deep Dive" at the [Silicon Valley ReactJS Meetup](http://www.meetup.com/Silicon-Valley-ReactJS-Meetup/events/232236845/) on August 17th. +- I ([@josephsavona](https://github.com/josephsavona)) will be speaking about Relay at [React Rally](http://www.reactrally.com) on August 25th. + +We can't wait to share the new code with you and are working as fast as we can to do so! diff --git a/docs/acknowledgements.md b/docs/acknowledgements.md index cb1cd3e6df..19894764be 100644 --- a/docs/acknowledgements.md +++ b/docs/acknowledgements.md @@ -2,6 +2,7 @@ id: acknowledgements title: Acknowledgements layout: single +permalink: acknowledgements.html --- We'd like to thank all of our contributors: diff --git a/docs/contributing/design-principles.md b/docs/contributing/design-principles.md new file mode 100644 index 0000000000..3027aa2a34 --- /dev/null +++ b/docs/contributing/design-principles.md @@ -0,0 +1,162 @@ +--- +id: design-principles +title: Design Principles +layout: contributing +permalink: contributing/design-principles.html +--- + +After using React in a couple of applications, you might be interested in contributing to React. Before [diving into specifics](https://github.com/facebook/react/blob/master/CONTRIBUTING.md), we think it's important to establish a few design principles guiding our decisions about changes in React. + +We wrote this document so that you have a better idea of how we decide what React does and what React doesn't do, and what our development philosophy is like. While we are excited to see community contributions, we are not likely to choose a path that violates one or more of these principles. + +>**Note:** +> +>This document assumes a strong understanding of React. It describes the design principles of *React itself*, not React components or applications. +> +>For an introduction to React, check out [Thinking in React](/react/docs/thinking-in-react.html) instead. + +### Composition + +The key feature of React is composition of components. Components written by different people should work well together. It is important to us that you can add functionality to a component without causing rippling changes throughout the codebase. + +For example, it should be possible to introduce some local state into a component without changing any of the components using it. Similarly, it should be possible to add some initialization and teardown code to any component when necessary. + +There is nothing "bad" about using state or lifecycle hooks in components. Like any powerful features, they should be used in moderation, but we have no intention to remove them. On the contrary, we think they are integral parts of what makes React useful. We might enable [more functional patterns](https://github.com/reactjs/react-future/tree/master/07%20-%20Returning%20State) in the future, but both local state and lifecycle hooks will be a part of that model. + +Components are often described as "just functions" but in our view they need to be more than that to be useful. In React, components describe any composable behavior, and this includes rendering, lifecycle, and state. Some external libraries like [Relay](http://facebook.github.io/relay/) augment components with other responsibilities such as describing data dependencies. It is possible that those ideas might make it back into React too in some form. + +### Common Abstraction + +In general we [resist adding features](https://www.youtube.com/watch?v=4anAwXYqLG8) that can be implemented in userland. We don't want to bloat your apps with useless library code. However, there are exceptions to this. + +For example, if React didn't provide support for local state or lifecycle hooks, people would create custom abstractions for them. When there are multiple abstractions competing, React can't enforce or take advantage of the properties of either of them. It has to work with the lowest common denominator. + +This is why sometimes we add features to React itself. If we notice that many components implement a certain feature in incompatible or inefficient ways, we might prefer to bake it into React. We don't do it lightly. When we do it, it's because we are confident that raising the abstraction level benefits the whole ecosystem. State, lifecycle hooks, cross-browser event normalization are good examples of this. + +We always discuss such improvement proposals with the community. You can find some of those discussions by the [“big picture”](https://github.com/facebook/react/issues?q=is%3Aopen+is%3Aissue+label%3A%22big+picture%22) label on the React issue tracker. + +### Escape Hatches + +React is pragmatic. It is driven by the needs of the products written at Facebook. While it is influenced by some paradigms that are not yet fully mainstream such as functional programming, staying accessible to a wide range of developers with different skills and experience levels is an explicit goal of the project. + +If we want to deprecate a pattern that we don't like, it is our responsibility to consider all existing use cases for it and [educate the community about the alternatives](/react/blog/2016/07/13/mixins-considered-harmful.html) before we deprecate it. If some pattern that is useful for building apps is hard to express in a declarative way, we will [provide an imperative API](/react/docs/more-about-refs.html) for it. If we can't figure out a perfect API for something that we found necessary in many apps, we will [provide a temporary subpar working API](/react/docs/context.html) as long as it is possible to get rid of it later and it leaves the door open for future improvements. + +### Stability + +We value API stability. At Facebook, we have more than 20 thousand components using React. Many other companies, including [Twitter](https://twitter.com/) and [Airbnb](https://www.airbnb.com/), are also heavy users of React. This is why we are usually reluctant to change public APIs or behavior. + +However we think stability in the sense of "nothing changes" is overrated. It quickly turns into stagnation. Instead, we prefer the stability in the sense of "It is heavily used in production, and when something changes, there is a clear (and preferably automated) migration path." + +When we deprecate a pattern, we study its internal usage at Facebook and add deprecation warnings. They let us assess the impact of the change. Sometimes we back out if we see that it is too early, and we need to think more strategically about getting the codebases to the point where they are ready for this change. + +If we are confident that the change is not too disruptive and the migration strategy is viable for all use cases, we release the deprecation warning to the open source community. We are closely in touch with many users of React outside of Facebook, and we monitor popular open source projects and guide them in fixing those deprecations. + +Given the sheer size of the Facebook React codebase, successful internal migration is often a good indicator that other companies won't have problems either. Nevertheless sometimes people point out additional use cases we haven't thought of, and we add escape hatches for them or rethink our approach. + +We don't deprecate anything without a good reason. We recognize that sometimes deprecations warnings cause frustration but we add them because deprecations clean up the road for the improvements and new features that we and many people in the community consider valuable. + +For example, we added a [warning about unknown DOM props](/react/warnings/unknown-prop.html) in React 15.2.0. Many projects were affected by this. However fixing this warning is important so that we can introduce the support for [custom attributes](https://github.com/facebook/react/issues/140) to React. There is a reason like this behind every deprecation that we add. + +When we add a deprecation warning, we keep it for the rest of the current major version, and [change the behavior in the next major version](/react/blog/2016/02/19/new-versioning-scheme.html). If there is a lot of repetitive manual work involved, we release a [codemod](https://www.youtube.com/watch?v=d0pOgY8__JM) script that automates most of the change. Codemods enable us to move forward without stagnation in a massive codebase, and we encourage you to use them as well. + +You can find the codemods that we released in the [react-codemod](https://github.com/reactjs/react-codemod) repository. + +### Interoperability + +We place high value in interoperability with existing systems and gradual adoption. Facebook has a massive non-React codebase. Its website uses a mix of a server-side component system called XHP, internal UI libraries that came before React, and React itself. It is important to us that any product team can [start using React for a small feature](https://www.youtube.com/watch?v=BF58ZJ1ZQxY) rather than rewrite their code to bet on it. + +This is why React provides escape hatches to work with mutable models, and tries to work well together with other UI libraries. You can wrap an existing imperative UI into a declarative component, and vice versa. This is crucial for gradual adoption. + +### Scheduling + +Even when your components are described as functions, when you use React you don't call them directly. Every component returns a [description of what needs to be rendered](/react/blog/2015/12/18/react-components-elements-and-instances.html#elements-describe-the-tree), and that description may include both user-written components like `Marc was almost ready to implement his "hello world" React app pic.twitter.com/ptdg4yteF1
— Thomas Fuchs (@thomasfuchs) March 12, 2016
+ Hello, ! + It is {this.props.date.toTimeString()} +
+ ); + } +}); + +setInterval(function() { + ReactDOM.render( +You {text} this. Click to toggle. diff --git a/docs/docs/03-interactivity-and-dynamic-uis.ko-KR.md b/docs/docs/03-interactivity-and-dynamic-uis.ko-KR.md index ef3b3526c6..b1f94053ed 100644 --- a/docs/docs/03-interactivity-and-dynamic-uis.ko-KR.md +++ b/docs/docs/03-interactivity-and-dynamic-uis.ko-KR.md @@ -1,7 +1,7 @@ --- id: interactivity-and-dynamic-uis-ko-KR title: 상호 작용 및 동적 UI -permalink: interactivity-and-dynamic-uis-ko-KR.html +permalink: docs/interactivity-and-dynamic-uis-ko-KR.html prev: jsx-gotchas-ko-KR.html next: multiple-components-ko-KR.html --- @@ -19,7 +19,7 @@ var LikeButton = React.createClass({ this.setState({liked: !this.state.liked}); }, render: function() { - var text = this.state.liked ? 'like' : 'haven\'t liked'; + var text = this.state.liked ? 'liked' : 'haven\'t liked'; return (
You {text} this. Click to toggle. diff --git a/docs/docs/03-interactivity-and-dynamic-uis.md b/docs/docs/03-interactivity-and-dynamic-uis.md index c945a3a694..57b5ff8efa 100644 --- a/docs/docs/03-interactivity-and-dynamic-uis.md +++ b/docs/docs/03-interactivity-and-dynamic-uis.md @@ -1,7 +1,7 @@ --- id: interactivity-and-dynamic-uis title: Interactivity and Dynamic UIs -permalink: interactivity-and-dynamic-uis.html +permalink: docs/interactivity-and-dynamic-uis.html prev: jsx-gotchas.html next: multiple-components.html --- @@ -23,7 +23,7 @@ class LikeButton extends React.Component { this.setState({liked: !this.state.liked}); } render() { - const text = this.state.liked ? 'like' : 'haven\'t liked'; + const text = this.state.liked ? 'liked' : 'haven\'t liked'; return (
You {text} this. Click to toggle. @@ -63,10 +63,10 @@ React считает интерфейсы обыкновенными конеч **Старайтесь делать компоненты без состояния.** Следуя этому правилу, вы будете выносить работу с состоянием с уровня представления в другие, более подходящие места. Тем самым, вы снизите сложность приложения, упрощая его понимание. Основной принцип такой: создаются несколько компонентов без состояния, которые формируют дерево. Они будут заниматься только отрисовкой данных. А все данные для них будут у родительского компонента, который будет на вершине этого дерева компонентов. Он и будет передавать данные дочерним узлам через `props`. Этот компонент с общим состоянием содержит в себе всю логику взаимодействия, а дочерние компоненты будут только отрисовывать данные, которые будут у них в `props`. - + ## Какие данные *надо* помещать в состояние? -**Состояние должно содержать данные, которые нужны для обновления интерфейса.** В реальных приложениях такие данные, как правило, незначительны по объему, и могут быть сериализованы в JSON. Когда вы создаете компонент с состоянием, старайтесь поместить в него минимум данных. А уже внутри метода `render()` вычисляйте остальные данные, используя значения из состояния. +**Состояние должно содержать данные, которые нужны для обновления интерфейса.** В реальных приложениях такие данные, как правило, незначительны по объему, и могут быть сериализованы в JSON. Когда вы создаете компонент с состоянием, старайтесь поместить в него минимум данных. А уже внутри метода `render()` вычисляйте остальные данные, используя значения из состояния. Со временем вы увидите, что такой подход позволяет создавать более стройные и устойчивые к изменениям приложения. Добавление в состояние лишних данных требует от вас дополнительных затрат на их синхронизацию. Но этого можно избежать, если позволить React делать все эти вычисления за вас. ## Какие данные *не надо* помещать в состояние? diff --git a/docs/docs/03-interactivity-and-dynamic-uis.zh-CN.md b/docs/docs/03-interactivity-and-dynamic-uis.zh-CN.md index 1b9748f877..e6ece97de4 100644 --- a/docs/docs/03-interactivity-and-dynamic-uis.zh-CN.md +++ b/docs/docs/03-interactivity-and-dynamic-uis.zh-CN.md @@ -1,7 +1,7 @@ --- id: interactivity-and-dynamic-uis-zh-CN title: 动态交互式用户界面 -permalink: interactivity-and-dynamic-uis-zh-CN.html +permalink: docs/interactivity-and-dynamic-uis-zh-CN.html prev: jsx-gotchas-zh-CN.html next: multiple-components-zh-CN.html --- @@ -19,7 +19,7 @@ var LikeButton = React.createClass({ this.setState({liked: !this.state.liked}); }, render: function() { - var text = this.state.liked ? 'like' : 'haven\'t liked'; + var text = this.state.liked ? 'liked' : 'haven\'t liked'; return (
You {text} this. Click to toggle.
@@ -42,9 +42,9 @@ React 里只需把事件处理器(event handler)以骆峰命名(camelCased
在幕后,React 做了一些操作来让代码高效运行且易于理解。
-**Autobinding:** 在 JavaScript 里创建回调的时候,为了保证 `this` 的正确性,一般都需要显式地绑定方法到它的实例上。在 React,所有方法被自动绑定到了它的组件实例上(除非使用ES6的class符号)。React 还缓存这些绑定方法,所以 CPU 和内存都是非常高效。而且还能减少打字!
+**自动绑定:** 在 JavaScript 里创建回调的时候,为了保证 `this` 的正确性,一般都需要显式地绑定方法到它的实例上。在 React 中,所有方法被自动绑定到了它的组件实例上([除非使用ES6的class符号](/react/docs/reusable-components.html#no-autobinding))。React 还缓存这些绑定方法,所以 CPU 和内存都是非常高效。而且还能减少打字!
-**事件代理 :** React 实际并没有把事件处理器绑定到节点本身。当 React 启动的时候,它在最外层使用唯一一个事件监听器处理所有事件。当组件被加载和卸载时,只是在内部映射里添加或删除事件处理器。当事件触发,React 根据映射来决定如何分发。当映射里处理器时,会当作空操作处理。参考 [David Walsh 很棒的文章](http://davidwalsh.name/event-delegate) 了解这样做高效的原因。
+**事件代理:** React 实际并没有把事件处理器绑定到节点本身。当 React 启动的时候,它在最外层使用唯一一个事件监听器处理所有事件。当组件被加载和卸载时,只是在内部映射里添加或删除事件处理器。当事件触发,React 根据映射来决定如何分发。当映射里没有事件处理函数时,会当作空操作处理。参考 [David Walsh 很棒的文章](http://davidwalsh.name/event-delegate) 了解这样做高效的原因。
## 组件其实是状态机(State Machines)
@@ -54,7 +54,7 @@ React 里,只需更新组件的 state,然后根据新的 state 重新渲染
## State 工作原理
-常用的通知 React 数据变化的方法是调用 `setState(data, callback)`。这个方法会合并(merge) `data` 到 `this.state`,并重新渲染组件。渲染完成后,调用可选的 `callback` 回调。大部分情况下不需要提供 `callback`,因为 React 会负责把界面更新到最新状态。
+常用的通知 React 数据变化的方法是调用 `setState(data, callback)`。这个方法会合并(merge) `data` 到 `this.state`,并重新渲染组件。重新渲染完成后,调用可选的 `callback` 回调。大部分情况下不需要提供 `callback`,因为 React 会负责把界面更新到最新状态。
## 哪些组件应该有 State?
@@ -66,12 +66,12 @@ React 里,只需更新组件的 state,然后根据新的 state 重新渲染
## 哪些 *应该* 作为 State?
-**State 应该包括那些可能被组件的事件处理器改变并触发用户界面更新的数据。** 真实的应用中这种数据一般都很小且能被 JSON 序列化。当创建一个状态化的组件时,想象一下表示它的状态最少需要哪些数据,并只把这些数据存入 `this.state`。在 `render()` 里再根据 state 来计算你需要的其它数据。你会发现以这种方式思考和开发程序最终往往是正确的,因为如果在 state 里添加冗余数据或计算所得数据,需要你经常手动保持数据同步,不能让 React 来帮你处理。
+**State 应该包括那些可能被组件的事件处理器改变并触发用户界面更新的数据。** 真实的应用中这种数据一般都很小且能被 JSON 序列化。当创建一个状态化的组件时,思考一下表示它的状态最少需要哪些数据,并只把这些数据存入 `this.state`。在 `render()` 里再根据 state 来计算你需要的其它数据。你会发现以这种方式思考和开发程序最终往往是正确的,因为如果在 state 里添加冗余数据或计算所得数据,那么你就需要经常手动保持数据同步,而不能让 React 来帮你处理。
## 哪些 *不应该* 作为 State?
-`this.state` 应该仅包括能表示用户界面状态所需的最少数据。因些,它不应该包括:
+`this.state` 应该仅包括能表示用户界面状态所需的最少数据。因此,它不应该包括:
* **计算所得数据:** 不要担心根据 state 来预先计算数据 —— 把所有的计算都放到 `render()` 里更容易保证用户界面和数据的一致性。例如,在 state 里有一个数组(listItems),我们要把数组长度渲染成字符串, 直接在 `render()` 里使用 `this.state.listItems.length + ' list items'` 比把它放到 state 里好的多。
* **React 组件:** 在 `render()` 里使用当前 props 和 state 来创建它。
-* **基于 props 的重复数据:** 尽可能使用 props 来作为实际状态的源。把 props 保存到 state 的一个有效的场景是需要知道它以前值的时候,因为 props 可能因为父组件重绘的结果而变化。
+* **基于 props 的重复数据:** 尽可能使用 props 来作为实际状态的源。把 props 保存到 state 的一个有效的场景是需要知道它以前值的时候,因为 props 可能因为父组件的重绘而变化。
diff --git a/docs/docs/04-multiple-components.it-IT.md b/docs/docs/04-multiple-components.it-IT.md
index 84b6f80aa9..91a1b9f432 100644
--- a/docs/docs/04-multiple-components.it-IT.md
+++ b/docs/docs/04-multiple-components.it-IT.md
@@ -1,7 +1,7 @@
---
id: multiple-components-it-IT
title: Componenti Multipli
-permalink: multiple-components-it-IT.html
+permalink: docs/multiple-components-it-IT.html
prev: interactivity-and-dynamic-uis-it-IT.html
next: reusable-components-it-IT.html
---
diff --git a/docs/docs/04-multiple-components.ja-JP.md b/docs/docs/04-multiple-components.ja-JP.md
index 1d6e363ec7..39b5dfe848 100644
--- a/docs/docs/04-multiple-components.ja-JP.md
+++ b/docs/docs/04-multiple-components.ja-JP.md
@@ -1,7 +1,7 @@
---
id: multiple-components
title: 複数のコンポーネント
-permalink: multiple-components-ja-JP.html
+permalink: docs/multiple-components-ja-JP.html
prev: interactivity-and-dynamic-uis-ja-JP.html
next: reusable-components-ja-JP.html
---
diff --git a/docs/docs/04-multiple-components.ko-KR.md b/docs/docs/04-multiple-components.ko-KR.md
index ec8d8c751d..47f763103c 100644
--- a/docs/docs/04-multiple-components.ko-KR.md
+++ b/docs/docs/04-multiple-components.ko-KR.md
@@ -1,7 +1,7 @@
---
id: multiple-components-ko-KR
title: 복합 컴포넌트
-permalink: multiple-components-ko-KR.html
+permalink: docs/multiple-components-ko-KR.html
prev: interactivity-and-dynamic-uis-ko-KR.html
next: reusable-components-ko-KR.html
---
diff --git a/docs/docs/04-multiple-components.md b/docs/docs/04-multiple-components.md
index 08009746f6..24323a9cf1 100644
--- a/docs/docs/04-multiple-components.md
+++ b/docs/docs/04-multiple-components.md
@@ -1,7 +1,7 @@
---
id: multiple-components
title: Multiple Components
-permalink: multiple-components.html
+permalink: docs/multiple-components.html
prev: interactivity-and-dynamic-uis.html
next: reusable-components.html
---
diff --git a/docs/docs/04-multiple-components.zh-CN.md b/docs/docs/04-multiple-components.zh-CN.md
index 309d44eb97..84e2e47959 100644
--- a/docs/docs/04-multiple-components.zh-CN.md
+++ b/docs/docs/04-multiple-components.zh-CN.md
@@ -1,7 +1,7 @@
---
id: multiple-components-zh-CN
title: 复合组件
-permalink: multiple-components-zh-CN.html
+permalink: docs/multiple-components-zh-CN.html
prev: interactivity-and-dynamic-uis-zh-CN.html
next: reusable-components-zh-CN.html
---
@@ -54,9 +54,9 @@ ReactDOM.render(
## 从属关系
-上面例子中,`Avatar` 拥有 `PagePic` 和 `PageLink` 的实例。`拥有者` 就是给其它组件设置 `props` 的那个组件。更正式地说,如果组件 `Y` 在 `render()` 方法是创建了组件 `X`,那么 `Y` 就拥有 `X`。上面讲过,组件不能修改自身的 `props` - 它们总是与它们拥有者设置的保持一致。这是保持用户界面一致性的基本不变量。
+上面例子中,`Avatar` 拥有 `PagePic` 和 `PageLink` 的实例。`拥有者` 就是给其它组件设置 `props` 的那个组件。更正式地说,如果组件 `Y` 在 `render()` 方法是创建了组件 `X`,那么 `Y` 就拥有 `X`。上面讲过,组件不能修改自身的 `props` - 它们总是与它们的拥有者所设置的值保持一致。这是保持用户界面一致性的基本不变量。
-把从属关系与父子关系加以区别至关重要。从属关系是 React 特有的,而父子关系简单来讲就是DOM 里的标签的关系。在上一个例子中,`Avatar` 拥有 `div`、`PagePic` 和 `PageLink` 实例,`div` 是 `PagePic` 和 `PageLink` 实例的**父级**(但不是拥有者)。
+把从属关系与父子关系加以区别至关重要。从属关系是 React 特有的,而父子关系简单来讲就是 DOM 里的标签的关系。在上一个例子中,`Avatar` 拥有 `div`、`PagePic` 和 `PageLink` 实例,`div` 是 `PagePic` 和 `PageLink` 实例的**父级**(但不是拥有者)。
## 子级
@@ -66,7 +66,7 @@ ReactDOM.render(