Merge pull request #5599 from plotly/cam/update-md-files

docs: Update release, docs readme files with info, corrections

Author: camdecoster

RELEASE.md

@@ -110,9 +110,9 @@ Once these are verified working, you can move on to publishing the release.
 
 ### Publishing to PyPI
 
-The final step is to publish the release to PyPI. **You will need special permissions from Plotly leadership to do this.**.
+The final step is to publish the release to PyPI. **You will need special permissions from Plotly leadership to do this.**
 
-You must install first install [Twine](https://pypi.org/project/twine/) (`pip install twine`) if not already installed.
+You must first install [Twine](https://pypi.org/project/twine/) (`pip install twine`) if not already installed.
 
 Publishing to PyPI:
 ```bash
@@ -132,10 +132,21 @@ Your account must have permissions to publish to the `plotly` project on PyPI.
 start by doing it first if not. Then merge `main` into `doc-prod` to deploy the doc related
 to features in the release.
 3. in a clone of the [`graphing-library-docs` repo](https://github.com/plotly/graphing-library-docs):
-    1. bump the version of plotly.py in  `_data/pyversion.json`
+    1. bump the version of plotly.py in `_data/pyversion.json`
     2. bump the version of plotly.js with `cd _data && python get_plotschema.py <PLOTLY.JS VERSION>` fixing any errors that come up.
-      - If plotly.js contains any new traces or trace or layout attributes, you'll get a warning `“missing key in attributes: <attribute-name>`. To resolve, add the attribute to the relevant section in `/_data/orderings.json` in the position you want it to appear in the reference docs.
-    3. rebuild the Algolia `schema` index with `ALGOLIA_API_KEY=<key> make update_ref_search`
+
+       **About `_data/orderings.json`:** `get_plotschema.py` downloads the raw `plot-schema.json` from the specified plotly.js release and uses `_data/orderings.json` (which lives in `graphing-library-docs`, not plotly.js) to determine the order in which traces, trace attributes, and layout attributes appear in the [reference documentation](https://plotly.com/python/reference/). The file has three sections:
+       - `layout` — top-level layout attributes (e.g. `hovermode`, `clickmode`, `xaxis`)
+       - `traces` — order of trace types (e.g. `scatter`, `bar`, `pie`)
+       - `trace_attr_order` — order of attributes shared across traces
+
+       If plotly.js adds new traces or trace/layout attributes that aren't listed in `orderings.json`, `get_plotschema.py` prints a warning like `missing key in attributes: <attribute-name>` and appends the missing entry to the end of its section. To resolve:
+
+       - Add each missing attribute to the appropriate section of `/_data/orderings.json` in the position you want it to appear in the reference docs.
+       - When in doubt about trace-attribute placement, match plotly.js's native order: open the regenerated `_data/plotschema.json` and find where plotly.js itself places the attribute (e.g. inspect a representative trace's `attributes` keys in order). Following the native order keeps related attributes grouped (for example, `texttemplate` → `texttemplatefallback` → `texttemplatesrc`).
+       - For new top-level layout attributes, group them with semantically related entries rather than appending to the end (for example, a new click-behavior attribute like `clickanywhere` belongs next to `clickmode`).
+       - Re-run `python get_plotschema.py <PLOTLY.JS VERSION>` after editing `orderings.json` and confirm the warnings are gone.
+    3. Rebuild the Algolia `schema` index with `ALGOLIA_API_KEY=<key> make update_ref_search`
     4. Rebuild the Algolia `python` index with `ALGOLIA_API_KEY=<key> make update_python_search`
     5. Commit and push the changes to `master` in that repo
 
@@ -158,5 +169,5 @@ PyPI RC (no special flags, just the `rc1` suffix):
 (plotly_dev) $ twine upload dist/plotly-X.Y.Zrc1*
 ```
 
-The `--tag next` part ensures that users won't install this version unless
-they explicitly ask for the version or for the version with the `next` tag.
+The `rc1` suffix ensures that users won't install this version by default —
+they must explicitly request it (e.g., `pip install plotly==X.Y.Zrc1`).