update instructions for updateplotlyjs command

Author: emilykl

CONTRIBUTING.md

@@ -264,39 +264,54 @@ Two kinds of Jupyter support are included:
 
 ### Updating to a New Version of plotly.js
 
-First, update the version of the `plotly.js` dependency in `js/package.json`.
-Once you have done that,
-run the `updateplotlyjs` command:
+We typically update the plotly.js version in plotly.py after every new plotly.js release.
 
-```bash
-python commands.py updateplotlyjs
-```
+_Usually, the mostly-automated steps below are sufficient. However, in some cases, manual changes may be needed. For example, [plotly.js/#7580](https://github.com/plotly/plotly.js/pull/7580) required [#5464](https://github.com/plotly/plotly.py/pull/5464) and [#5465](https://github.com/plotly/plotly.py/pull/5465). This is most often the case when plotly.js is updated to accept additional value types for an attribute; plotly.py has its own validation layer which may need to be updated. When in doubt, test out a new plotly.js feature in plotly.py to verify that everything works._
 
-This downloads new versions of `plot-schema.json` and `plotly.min.js` from the `plotly/plotly.js` GitHub repository
-and places them in `codegen/resources/` and `plotly/package_data/`, respectively.
+1. Create a new branch off of `main`.
 
-It then does the following:
- - Regenerates all of the `graph_objs` classes based on the new schema
- - Runs `npm install` in `js/` to refresh `js/package-lock.json` against the new `plotly.js`
- - Runs `npm run build` to rebuild the JupyterLab extension and FigureWidget bundles in `plotly/labextension` and `plotly/package_data/widgetbundle.js`.
+2. Manually update the version of the `plotly.js` dependency in `js/package.json`.
 
-Commit the updated files under:
- - `codegen/resources/`
- - `js/`
- - `plotly/graph_objs/`
- - `plotly/labextension/`
- - `plotly/offline/`
- - `plotly/package_data/`
+3. Run the `updateplotlyjs` command:
 
-If you need to skip the `npm` steps entirely (e.g. `npm` isn't available),
-set the `SKIP_NPM=1` environment variable:
+    ```bash
+    python commands.py updateplotlyjs
+    ```
 
-```bash
-SKIP_NPM=1 python commands.py updateplotlyjs
-```
+    This command does the following:
 
-If you do skip it, you'll need to find a way to manually run `npm install && npm run build` in `js/` before committing,
-so that the lockfile and build artifacts stay in sync with `js/package.json`.
+    - Downloads new versions of `plot-schema.json` and `plotly.min.js` from the [plotly.js GitHub repository](https://github.com/plotly/plotly.js)
+and places them in `codegen/resources/` and `plotly/package_data/`, respectively.
+    - Updates `plotly/offline/_plotlyjs_version.py` with the new version
+    - Regenerates all of the classes under `graph_objs/` (`go.Figure`, `go.Layout`, etc.), and `plotly/validators/_validators.json`, based on the new schema 
+    - Runs `npm install` in `js/` to update `js/package-lock.json`
+    - Runs `npm run build` in `js/` to rebuild the JupyterLab extension and FigureWidget bundles, which updates the artifacts in `plotly/labextension` and `plotly/package_data/widgetbundle.js`.
+
+    > Note: To skip the `npm` steps entirely (e.g. if `npm` isn't available), you can set the `SKIP_NPM=1` environment variable:
+    >
+    > ```bash
+    > SKIP_NPM=1 python commands.py updateplotlyjs
+    > ```
+    >
+    > However, before proceeding further, you'll still need to somehow run `npm install && npm run build` in `js/` before committing, so that the lockfile and build artifacts stay in sync with `js/package.json`.
+
+4. Commit the updated files under:
+    - `codegen/resources/`
+    - `js/`
+    - `plotly/graph_objs/`
+    - `plotly/labextension/`
+    - `plotly/offline/`
+    - `plotly/package_data/`
+
+5. To double-check that the update worked properly, you can use this one-liner:
+
+    ```bash
+    pip install -e . && python -c "import plotly.graph_objects as go; fig = go.Figure([go.Scatter(y=[2,1,3])]); fig.show()"
+    ```
+
+    The plot will open in a browser window; hover over the Plotly logo in the modebar in the upper-right corner to verify that the plotly.js version is correct.
+
+6. Open a PR into `main`.
 
 ### Using a Development Branch of Plotly.js