Skip to content

Update release instructions #5364

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
merged 2 commits into from
Oct 3, 2025
Merged

Update release instructions #5364

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10c3321
Update RELEASE.md
emilykl Oct 2, 2025
ea6398e
review comments
emilykl Oct 3, 2025
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
109 changes: 75 additions & 34 deletions RELEASE.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should maintain plotly.py and plotly.js to match what's shown in the repos. Was there something that prompted the change?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you mean by "to match what's shown in the repos"?

I changed it because I think the capitals make it easier to read, but I could be convinced otherwise.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean that we refer to the libraries as "plotly.xy" instead of "Plotly.xy" in the README for each repo. It's not a big deal, but I always try to use the proper name for an item. Like "GitHub" instead of "Github".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah fair enough, I guess we should keep lowercase unless/until we change the styling across the board.

Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

## Release process - full release of `plotly` package

This is the release process for releasing `plotly.py` version `X.Y.Z`, including changelogs, Github release and forum announcement.
This is the release process for releasing Plotly.py version `X.Y.Z`, including changelogs, GitHub release and forum announcement.

### Finalize changelog

Expand All @@ -13,59 +13,100 @@ Make sure the changelog includes the version being published at the top, along
with the expected publication date.

Use the `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`
labels for all changes to plotly.py. If the version of plotly.js has
labels for all changes to Plotly.py. If the version of Plotly.js has
been updated, include this as the first `Updated` entry. Call out any
notable changes as sub-bullets (new trace types in particular), and provide
a link to the plotly.js CHANGELOG.
a link to the Plotly.js CHANGELOG.

### Finalize versions
### Update version numbers

**Create a branch `git checkout -b release-X.Y.Z` *from the tip of `origin/main`*.**
**Create a release branch `git checkout -b release-X.Y.Z` _from the tip of `origin/main`_.**

Manually update the versions to `X.Y.Z` in the files specified below.
- Manually update the versions to `X.Y.Z` in the files specified below:
- `pyproject.toml`
- update version
- `CHANGELOG.md`
- update version and release date
- finalize changelog entries according to instructions above
- `CITATION.cff`
- update version and release date
- Run `uv lock` to update the version number in the `uv.lock` file (do not update manually)
- Commit and push your changes to the release branch:
- `git add -u`
- `git commit -m "version changes for vX.Y.Z"`
- `git push`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- `git add -u`
- `git commit -m "version changes for vX.Y.Z"`
- `git push`
```sh
git add -u
git commit -m "version changes for vX.Y.Z"
git push
```

- Create a GitHub pull request from `release-X.Y.Z` to `main` and wait for CI to be green
- On the release branch, create and push a tag for the release:
- `git tag vX.Y.Z`
- `git push origin vX.Y.Z`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, the closing ``` isn't showing up in the suggestion for some reason.

Suggested change
- `git tag vX.Y.Z`
- `git push origin vX.Y.Z`
```sh
git tag vX.Y.Z
git push origin vX.Y.Z


- `pyproject.toml`
+ update version
- `CHANGELOG.md`
+ update the release date
- Commit your changes on the branch:
+ `git commit -a -m "version changes for vX.Y.Z"`
- Create a tag for Github release
+ `git tag vX.Y.Z`
+ `git push --atomic origin release-X.Y.Z vX.Y.Z`
- Create a Github pull request from `release-X.Y.Z` to `main` and wait for CI to be green
### Manual QA in Jupyter

### Download and QA CI Artifacts
We don't currently have automated tests for Jupyter, so we do this QA step manually.

The `full_build` job in the `release_build` workflow in CircleCI produces a tarball of artifacts `output.tgz` which you should download and decompress, which will give you a directory called `output`. The filenames contained within will contain version numbers.
The `full_build` job in the `release_build` workflow in CircleCI produces a tarball of artifacts `output.tgz`
which you should download and decompress, which will give you a directory called `output`. The filenames within
will contain version numbers; make sure the version numbers are correct.

To locally install the PyPI dist, make sure you have an environment with JupyterLab installed (maybe one created with `conda create -n condatest python=3.10 jupyter anywidget pandas`):
Set up an environment with Jupyter, AnyWidget, and Pandas installed (`pip install jupyter anywidget pandas`). Then:

- `tar xzf output.tgz`
- unzip downloaded `output.tgz`
- `pip uninstall plotly`
- `conda uninstall plotly` (just in case!)
- `pip install path/to/output/dist/plotly-X.Y.X-py3-none-any.whl`
- `pip install path/to/output/dist/plotly-X.Y.Z-py3-none-any.whl`

You'll want to check, in both Lab and Notebook, **in a brand new notebook in each** so that there is no caching of previous results, that `go.Figure()` and `go.FigureWidget()` work without error.
You'll want to check, in both JupyterLab (launch with `jupyter lab`) and Jupyter Notebook (launch with `jupyter notebook`),
that `go.Figure()` and `go.FigureWidget()` work as expected.

### Publishing
Notes:
- **Start by creating a brand new notebook each time** so that there is no caching of previous results
- **Do not run the Jupyter commands from the root `plotly.py/` directory on your machine** because Jupyter may be confused
by metadata from previous Plotly.py builds

Once you're satisfied that things render in Lab and Notebook in Widget and regular mode,
you can publish the artifacts. **You will need special credentials from Plotly leadership to do this.**.
Code for testing `go.Figure()`:
```python
import plotly
import plotly.graph_objects as go

print(plotly.__version__) # Make sure version is correct
fig = go.Figure(data=go.Scatter(x=[1, 2, 3, 4], y=[1, 3, 2, 4]))
fig.show() # Figure should render in notebook
```

Code for testing `go.FigureWidget()`:
```python
import plotly
import plotly.graph_objects as go

print(plotly.__version__) # Make sure version is correct
fig = go.Figure(data=go.Scatter(x=[1, 2, 3, 4], y=[1, 3, 2, 4]))
figure_widget = go.FigureWidget(fig)
figure_widget # Figure should render in notebook
```

Once these are verified working, you can move on to publishing the release.

### Merge the release PR and make a GitHub release

- Merge the pull request you created above into `main`
- Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
- Enter the `vX.Y.Z` tag you created already above and make "Release title" the same string as the tag.
- Copy the changelog section for this version into "Describe this release"
- Upload the build artifacts downloaded in the previous step (`.tar` and `.whl`)

### Publishing to PyPI

The final step is to publish the release to PyPI. **You will need special permissions from Plotly leadership to do this.**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add some context or add instructions for who to contact?

Copy link
Contributor Author

@emilykl emilykl Oct 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doc is public so I'm not sure it makes sense to put more info here, but feel free to suggest different wording if you have an idea.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah! Good point. Ignore this one.


You must install first install [Twine](https://pypi.org/project/twine/) (`pip install twine`) if not already installed.

Publishing to PyPI:
```bash
(plotly_dev) $ cd path/to/output
(plotly_dev) $ twine upload plotly-X.Y.Z*
```

### Merge the PR and make a Release

1. Merge the pull request you created above into `main`
2. Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
3. Enter the `vX.Y.Z` tag you created already above and make "Release title" the same string as the tag.
4. Copy the changelog section for this version as the "Describe this release"
You will be prompted to enter an API token; this can be generated in your PyPI account settings.
Your account must have permissions to publish to the Plotly project on PyPI.

### Update documentation site

Expand All @@ -85,9 +126,9 @@ to features in the release.

### Notify Stakeholders

* Post an announcement to the Plotly Python forum, with links to the README installation instructions and to the CHANGELOG.
* Post an announcement to the [Plotly Python forum](https://community.plotly.com/c/plotly-python/5), with links to the README installation instructions and to the CHANGELOG.
* Update the previous announcement to point to this one
* Update the Github Release entry and CHANGELOG entry to have the nice title and a link to the announcement
* Update the GitHub Release entry and CHANGELOG entry to have the nice title and a link to the announcement
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👏

* Follow up on issues resolved in this release or forum posts with better answers as of this release

## Release process - Release *Candidate* of `plotly` package
Expand Down