From 10c3321cf5ac5d1fd498c30241642366eeba04ec Mon Sep 17 00:00:00 2001 From: Emily KL <4672118+emilykl@users.noreply.github.com> Date: Thu, 2 Oct 2025 12:12:31 -0400 Subject: [PATCH 1/2] Update RELEASE.md --- RELEASE.md | 109 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 34 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 471e076b91..a6165cc52c 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -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 @@ -13,46 +13,91 @@ 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` +- 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` - - `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.**. + +You must install first install [Twine](https://pypi.org/project/twine/) (`pip install twine`) if not already installed. Publishing to PyPI: ```bash @@ -60,12 +105,8 @@ Publishing to PyPI: (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 @@ -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 * 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 From ea6398ee1788ebd654c6e7c7123a6eb44167ce0b Mon Sep 17 00:00:00 2001 From: Emily KL <4672118+emilykl@users.noreply.github.com> Date: Fri, 3 Oct 2025 14:45:49 -0400 Subject: [PATCH 2/2] review comments --- RELEASE.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index a6165cc52c..aa6f094929 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -32,13 +32,17 @@ a link to the Plotly.js CHANGELOG. - 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` + ```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` + ```sh + $ git tag vX.Y.Z + $ git push origin vX.Y.Z + ``` ### Manual QA in Jupyter