Update RELEASE.md

emilykl · web-flow · commit 7957bedd1948 · 2025-10-02T12:12:31.000-04:00
diff --git a/RELEASE.md b/RELEASE.md
@@ -20,52 +20,88 @@ a link to the plotly.js CHANGELOG.
 
 ### Finalize versions
 
-**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:
+  - `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`
+
+### Manual QA in Jupyter
+
+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 within will contain version numbers; make sure the version numbers are correct.
+
+Set up an environment with Jupyter, AnyWidget, and Pandas installed (`pip install jupyter anywidget pandas`). Then:
+
+- unzip downloaded `output.tgz`
+- `pip uninstall plotly`
+- `pip install path/to/output/dist/plotly-X.Y.Z-py3-none-any.whl`
 
-Manually update the versions to `X.Y.Z` in the files specified below.
+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. 
 
- - `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
+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 builds 
 
-### Download and QA CI Artifacts
+Code for testing `go.Figure()`:
+```python
+import plotly
+import plotly.graph_objects as go
 
-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.
+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
+```
 
-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`):
+Code for testing `go.FigureWidget()`:
+```python
+import plotly
+import plotly.graph_objects as go
 
-- `tar xzf 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`
+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
+```
 
-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.
+Once these are verified working, you can move on to publishing the release.
 
-### Publishing
+### Merge the release PR and make a Github release
 
-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.**.
+- 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
 (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
 
