Developer migration documentation (#7358)

* Update the developer guide intro page
* Expand developer migration documentation

diff --git a/docs/docs/developers/index.md b/docs/docs/developers/index.md
index 536fde35302d72093dbfe0922df4d94c2df1abd4..ef8e4880b30eaa54373663f09bf7bbce04ae1744 100644 (file)
--- a/docs/docs/developers/index.md
+++ b/docs/docs/developers/index.md
@@ -18,8 +18,6 @@ Latest builds are available for testing at:
  - https://www.chartjs.org/dist/master/Chart.js
  - https://www.chartjs.org/dist/master/Chart.min.js
 
-> Note: Development builds are currently only available via HTTP, so in order to include them in [JSFiddle](https://jsfiddle.net) or [CodePen](https://codepen.io), you need to access these tools via HTTP as well.
-
 **WARNING: Development builds MUST not be used for production purposes or as replacement for CDN.**
 
 ## Browser support
@@ -37,12 +35,13 @@ Thanks to [BrowserStack](https://browserstack.com) for allowing our team to test
 
 ## Previous versions
 
+To migrate from version 3 to version 2, please see [the v3 migration guide](../getting-started/v3-migration).
+
 Version 2 has a completely different API than earlier versions.
 
 Most earlier version options have current equivalents or are the same.
 
-Please use the documentation that is available on [chartjs.org](https://www.chartjs.org/docs/) for the current version of Chart.js.
-
-Please note - documentation for previous versions are available on the GitHub repo.
+Please note - documentation for previous versions are available online or in the GitHub repo.
 
+- [2.9.3 Documentation](https://www.chartjs.org/docs/2.9.3/)
 - [1.x Documentation](https://github.com/chartjs/Chart.js/tree/v1.1.1/docs)

diff --git a/docs/docs/getting-started/v3-migration.md b/docs/docs/getting-started/v3-migration.md
index c9f573112e039d5a9c56a7691a0a0379a457e4fa..ebba06adde0a33122595ae74524b1bea13882621 100644 (file)
--- a/docs/docs/getting-started/v3-migration.md
+++ b/docs/docs/getting-started/v3-migration.md
@@ -166,6 +166,22 @@ Animation system was completely rewritten in Chart.js v3. Each property can now
 
 ## Developer migration
 
+While the end-user migration for Chart.js 3 is fairly straight-forward, the developer migration can be more complicated. Please reach out for help in the #dev [Slack](https://chartjs-slack.herokuapp.com/) channel if tips on migrating would be helpful.
+
+Some of the biggest things that have changed:
+* There is a completely rewritten and more performant animation system.
+  * `Element._model` and `Element._view` are no longer used and properties are now set directly on the elements. You will have to use the method `getProps` to access these properties inside most methods such as `inXRange`/`inYRange` and `getCenterPoint`. Please take a look at [the Chart.js-provided elements](https://github.com/chartjs/Chart.js/tree/master/src/elements) for examples.
+  * When building the elements in a controller, it's now suggested to call `updateElement` to provide the element properties. There are also methods such as `getSharedOptions` and `includeOptions` that have been added to skip redundant computation. Please take a look at [the Chart.js-provided controllers](https://github.com/chartjs/Chart.js/tree/master/src/controllers) for examples.
+* Scales introduced a new parsing API. This API takes user data and converts it into a more standard format. E.g. it allows users to provide numeric data as a `string` and converts it to a `number` where necessary. Previously this was done on the fly as charts were rendered. Now it's done up front with the ability to skip it for better performance if users provide data in the correct format. If you're using standard data format like `x`/`y` you may not need to do anything. If you're using a custom data format you will have to override some of the parse methods in `core.datasetController.js`. An example can be found in [chartjs-chart-financial](https://github.com/chartjs/chartjs-chart-financial), which uses an `{o, h, l, c}` data format.
+
+A few changes were made to controllers that are more straight-forward, but will affect all controllers:
+
+* Options:
+  * `global` was removed from the defaults namespace as it was unnecessary and sometimes inconsistent
+  * Dataset defaults are now under the chart type options instead of vice-versa. This was not able to be done when introduced in 2.x for backwards compatibility. Fixing it removes the biggest stumbling block that new chart developers encountered
+  * Scale default options need to be updated as described in the end user migration section (e.g. `x` instead of `xAxes` and `y` instead of `yAxes`)
+* `updateElement` was changed to `updateElements` and has a new method signature as described below. This provides performance enhancements such as allowing easier reuse of computations that are common to all elements and reducing the number of function calls
+
 ### Removed
 
 The following properties and methods were removed:

diff --git a/src/core/core.datasetController.js b/src/core/core.datasetController.js
index bc314e473be4fdde2af3feeca8b566a3211dd328..eb57b9d6bf0b9cc837b5c9f08c77a66297951bae 100644 (file)
--- a/src/core/core.datasetController.js
+++ b/src/core/core.datasetController.js
@@ -982,7 +982,7 @@ export default class DatasetController {
        }
 
        /**
-        * Utility for updating a element with new properties, using animations when appropriate.
+        * Utility for updating an element with new properties, using animations when appropriate.
         * @protected
         */
        updateElement(element, index, properties, mode) {