update instructions for updateplotlyjs command

Author: emilykl

CONTRIBUTING.md

@@ -264,39 +264,42 @@ 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:
+1. Create a new branch off of `main`.
 
-```bash
-python commands.py updateplotlyjs
-```
-
-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.
+2. Manually update the version of the `plotly.js` dependency in `js/package.json`.
 
-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`.
+3. Run the `updateplotlyjs` command:
 
-Commit the updated files under:
- - `codegen/resources/`
- - `js/`
- - `plotly/graph_objs/`
- - `plotly/labextension/`
- - `plotly/offline/`
- - `plotly/package_data/`
+    ```bash
+    python commands.py updateplotlyjs
+    ```
 
-If you need to skip the `npm` steps entirely (e.g. `npm` isn't available),
-set the `SKIP_NPM=1` environment variable:
+    This command does the following:
 
-```bash
-SKIP_NPM=1 python commands.py updateplotlyjs
-```
-
-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. Open a PR into `main`.
 
 ### Using a Development Branch of Plotly.js