Merge pull request #5364 from plotly/release-instructions-cleanup

Update release instructions

Author: emilykl

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,59 +13,104 @@ 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.
+
+### Update version numbers
+
+**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:
+    ```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:
+    ```sh
+    $ 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`
 
-### Finalize versions
+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. 
 
-**Create a branch `git checkout -b release-X.Y.Z` *from the tip of `origin/main`*.**
+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 
 
-Manually update the versions to `X.Y.Z` in the files specified below.
+Code for testing `go.Figure()`:
+```python
+import plotly
+import plotly.graph_objects as go
 
- - `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
+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
+```
 
-### Download and QA CI Artifacts
+Code for testing `go.FigureWidget()`:
+```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]))
+figure_widget = go.FigureWidget(fig)
+figure_widget  # 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`):
+Once these are verified working, you can move on to publishing the release.
 
-- `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`
+### Merge the release PR and make a GitHub release
 
-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.
+- 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
+### Publishing to PyPI
 
-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.**.
+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
 
@@ -85,9 +130,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