diff --git a/RELEASE.md b/RELEASE.md index 471e076b91..aa6f094929 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,95 @@ 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 @@ -60,12 +109,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 +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