Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
camdecoster merged 2 commits into from
May 19, 2026
+373 −41
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2f7ed14
docs: Update release, docs readme files with info, corrections
camdecoster May 18, 2026
913be14
Address PR feedback
camdecoster May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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`).
Loading