Added CHANGELOG

facebook · Jul 31, 2019 · c57d2a2 · c57d2a2
1 parent 9a36e56
commit c57d2a2
Show file tree

Hide file tree

Showing 2 changed files with 121 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,116 @@
+# React DevTools changelog
+
+<!-- ## [Unreleased]
+<details>
+  <summary>
+    Changes that have landed in master but are not yet released.
+    Click to see more.
+  </summary>
+  
+  <!-- Upcoming changes go here
+</details> -->
+
+## 4.0.0 (release date TBD)
+
+### General changes
+
+#### Improved performance
+One of the largest performance bottlenecks of the legacy DevTools extension was the amount of message it sent across its "bridge" (an abstraction around e.g. `postMessage`). The primary goal for the DevTools rewrite was to drastically reduce this traffic.
+
+The legacy DevTools also rendered the entire application tree in the form of a large DOM structure of nested nodes. A secondary goal of the rewrite was to avoid rendering unnecessary nodes by using a windowing library (specifically [react-window](https://github.com/bvaughn/react-window)).
+
+Learn more about these optimizations [here](https://github.com/bvaughn/react-devtools-experimental/blob/master/OVERVIEW.md).
+
+#### Component stacks
+
+React component authors have often requested a way to log warnings that include the React ["component stack"](https://reactjs.org/docs/error-boundaries.html#component-stack-traces). DevTools now provides an option to automatically append this information to warnings (`console.warn`) and errors (`console.error`).
+
+![Example console warning with component stack added](https://user-images.githubusercontent.com/29597/62228120-eec3da80-b371-11e9-81bb-018c1e577389.png)
+
+It can be disabled in the general settings panel:
+
+![Settings panel showing "component stacks" option](https://user-images.githubusercontent.com/29597/62227882-8f65ca80-b371-11e9-8a4e-5d27011ad1aa.png)
+
+### Components tree changes
+
+#### Component filters
+
+Large component trees can sometimes be hard to navigate. DevTools now provides a way to filter components so that you can hide ones you're not interested in seeing.
+
+![Component filter demo video](https://user-images.githubusercontent.com/29597/62229209-0bf9a880-b374-11e9-8f84-cebd6c1a016b.gif)
+
+Filter preferences are remembered between sessions.
+
+#### "Rendered by" list
+
+In React, an element's "owner" refers the thing that rendered it. Sometimes an element's parent is also its owner, but usually they're different. This distinction is important because props come from owners.
+
+![Example code](https://user-images.githubusercontent.com/29597/62229551-bbcf1600-b374-11e9-8411-8ff411f4f847.png)
+
+When you are debugging an unexpected prop value, you can save time if you skip over the parents.
+
+DevTools v4 adds a new "rendered by" list in the right hand pane that allows you to quickly step through the list of owners to speed up your debugging.
+
+![Example video showing the "rendered by" list](https://user-images.githubusercontent.com/29597/62229747-4152c600-b375-11e9-9930-3f6b3b92be7a.gif)
+
+#### Owners tree
+
+The inverse of the "rendered by" list is called the "owners tree". It is the list of things rendered by a particular component- (the things it "owns"). This view is kind of like looking at the source of the component's render method, and can be a helpful way to explore large, unfamiliar React applications.
+
+Double click a component to view the owners tree and click the "x" button to return to the full component tree:
+
+![Demo showing "owners tree" feature](https://user-images.githubusercontent.com/29597/62229452-84f90000-b374-11e9-818a-61eec6be0bb4.gif)
+
+#### Improved hooks support
+
+Hooks now have the same level of support as props and state: values can be edited, arrays and objects can be drilled into, etc.
+
+![Video demonstrating hooks support](https://user-images.githubusercontent.com/29597/62230532-d86c4d80-b376-11e9-8629-1b2129b210d6.gif)
+
+#### Improved search UX
+
+Legacy DevTools search filtered the components tree to show matching nodes as roots. This made the overall structure of the application harder to reason about, because it displayed ancestors as siblings.
+
+Search results are now shown inline similar to the browser's find-in-page search.
+
+![Video demonstrating the search UX](https://user-images.githubusercontent.com/29597/62230923-c63edf00-b377-11e9-9f95-aa62ddc8f62c.gif)
+
+#### Suspense toggle
+
+React's experimental [Suspense API](https://reactjs.org/docs/react-api.html#suspense) lets components "wait" for something before rendering. `<Suspense>` components can be used to specify loading states when components deeper in the tree are waiting to render.
+
+DevTools lets you test these loading states with a new toggle:
+
+![Video demonstrating suspense toggle UI](https://user-images.githubusercontent.com/29597/62231446-e15e1e80-b378-11e9-92d4-086751dc65fc.gif)
+
+### Profiler changes
+
+#### Reload and profile
+
+The profiler is a powerful tool for performing tuning React components. Legacy DevTools supported profiling, but only after it detected a profiling-capable version of React. Because of this there was no way to profile the initial _mount_ (one of the most performance sensitive parts) of an application.
+
+This feature is now supported with a "reload and profile" action:
+
+![Video demonstrating the reload-and-profile feature](https://user-images.githubusercontent.com/29597/62233455-7a8f3400-b37d-11e9-9563-ec334bfb2572.gif)
+
+#### Import/export
+
+Profiler data can now be exported and shared with other developers to enable easier collaboration.
+
+![Video demonstrating exporting and importing profiler data](https://user-images.githubusercontent.com/29597/62233911-6566d500-b37e-11e9-9052-692378c92538.gif)
+
+Exports include all commits, timings, interactions, etc.
+
+#### "Why did this render?"
+
+"Why did this render?" is a common question when profiling. The profiler now helps answer this question by recording which props and state change between renders.
+
+![Video demonstrating profiler "why did this render?" feature](https://user-images.githubusercontent.com/29597/62234698-0f932c80-b380-11e9-8cf3-a5183af0c388.gif)
+
+Because this feature adds a small amount of overhead, it can be disabled in the profiler settings panel.
+
+#### Component renders list
+
+The profiler now displays a list of each time the selected component rendered during a profiling session, along with the duration of each render. This list can be used to quickly jump between commits when analyzing the performance of a specific component.
+
+![Video demonstrating profiler's component renders list](https://user-images.githubusercontent.com/29597/62234547-bcb97500-b37f-11e9-9615-54fba8b574b9.gif)
diff --git a/OVERVIEW.md b/OVERVIEW.md
@@ -1,14 +1,14 @@
 # Overview
 
 The React DevTools extension consists of multiple pieces:
-* The **frontend** portion is the extension you see (the Elements tree, the Profiler, etc.).
+* The **frontend** portion is the extension you see (the Components tree, the Profiler, etc.).
 * The **backend** portion is invisible. It runs in the same context as React itself. When React commits changes to e.g. the DOM, the backend is responsible for notifying the frontend by sending a message through the **bridge** (an abstraction around e.g. `postMessage`).
 
-One of the largest performance bottlenecks of the old React DevTools was the amount of bridge traffic. Each time React commits an update, the backend sends every fiber that changed across the bridge, resulting in a lot of (JSON) serialization. The primary goal for the DevTools rewrite was to reduce this traffic. Instead of sending everything across the bridge, **the backend should only send the minimum amount required to render the Elements tree**. The frontend can request more information (e.g. an element's props) on demand, only as needed.
+One of the largest performance bottlenecks of the old React DevTools was the amount of bridge traffic. Each time React commits an update, the backend sends every fiber that changed across the bridge, resulting in a lot of (JSON) serialization. The primary goal for the DevTools rewrite was to reduce this traffic. Instead of sending everything across the bridge, **the backend should only send the minimum amount required to render the Components tree**. The frontend can request more information (e.g. an element's props) on demand, only as needed.
 
 The old DevTools also rendered the entire application tree in the form of a large DOM structure of nested nodes. A secondary goal of the rewrite was to avoid rendering unnecessary nodes by using a windowing library (specifically [react-window](https://github.com/bvaughn/react-window)).
 
-## Elements panel
+## Components panel
 
 ### Serializing the tree
 
@@ -160,9 +160,9 @@ The frontend stores its information about the tree in a map of id to objects wit
 * depth: `number` <sup>1</sup>
 * weight: `number` <sup>2</sup>
 
-<sup>1</sup> The `depth` value determines how much padding/indentation to use for the element when rendering it in the Elements panel. (This preserves the appearance of a nested tree, even though the view is a flat list.)
+<sup>1</sup> The `depth` value determines how much padding/indentation to use for the element when rendering it in the Components panel. (This preserves the appearance of a nested tree, even though the view is a flat list.)
 
-<sup>2</sup> The `weight` of an element is the number of elements (including itself) below it in the tree. We cache this property so that we can quickly determine the total number of Elements as well as to find the Nth element within that set. (This enables us to use windowing.) This value needs to be adjusted each time elements are added or removed from the tree, but we amortize this over time to avoid any big performance hits when rendering the tree.
+<sup>2</sup> The `weight` of an element is the number of elements (including itself) below it in the tree. We cache this property so that we can quickly determine the total number of Components as well as to find the Nth element within that set. (This enables us to use windowing.) This value needs to be adjusted each time elements are added or removed from the tree, but we amortize this over time to avoid any big performance hits when rendering the tree.
 
 #### Finding the element at index N