Skip to content

Commit 7957bed

Browse files
authored
Update RELEASE.md
1 parent a0de8c9 commit 7957bed

File tree

1 file changed

+65
-29
lines changed

1 file changed

+65
-29
lines changed

RELEASE.md

Lines changed: 65 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -20,52 +20,88 @@ a link to the plotly.js CHANGELOG.
2020

2121
### Finalize versions
2222

23-
**Create a branch `git checkout -b release-X.Y.Z` *from the tip of `origin/main`*.**
23+
**Create a release branch `git checkout -b release-X.Y.Z` *from the tip of `origin/main`*.**
24+
25+
- Manually update the versions to `X.Y.Z` in the files specified below:
26+
- `pyproject.toml`
27+
- update version
28+
- `CHANGELOG.md`
29+
- update version and release date
30+
- finalize changelog entries according to instructions above
31+
- `CITATION.cff`
32+
- update version and release date
33+
- Run `uv lock` to update the version number in the `uv.lock` file (do not update manually)
34+
- Commit and push your changes to the release branch:
35+
- `git add -u`
36+
- `git commit -m "version changes for vX.Y.Z"`
37+
- `git push`
38+
- Create a Github pull request from `release-X.Y.Z` to `main` and wait for CI to be green
39+
- On the release branch, create and push a tag for the release:
40+
- `git tag vX.Y.Z`
41+
- `git push origin vX.Y.Z`
42+
43+
### Manual QA in Jupyter
44+
45+
We don't currently have automated tests for Jupyter, so we do this QA step manually.
46+
47+
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.
48+
49+
Set up an environment with Jupyter, AnyWidget, and Pandas installed (`pip install jupyter anywidget pandas`). Then:
50+
51+
- unzip downloaded `output.tgz`
52+
- `pip uninstall plotly`
53+
- `pip install path/to/output/dist/plotly-X.Y.Z-py3-none-any.whl`
2454

25-
Manually update the versions to `X.Y.Z` in the files specified below.
55+
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.
2656

27-
- `pyproject.toml`
28-
+ update version
29-
- `CHANGELOG.md`
30-
+ update the release date
31-
- Commit your changes on the branch:
32-
+ `git commit -a -m "version changes for vX.Y.Z"`
33-
- Create a tag for Github release
34-
+ `git tag vX.Y.Z`
35-
+ `git push --atomic origin release-X.Y.Z vX.Y.Z`
36-
- Create a Github pull request from `release-X.Y.Z` to `main` and wait for CI to be green
57+
Notes:
58+
- **Start by creating a brand new notebook each time** so that there is no caching of previous results
59+
- **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
3760

38-
### Download and QA CI Artifacts
61+
Code for testing `go.Figure()`:
62+
```python
63+
import plotly
64+
import plotly.graph_objects as go
3965

40-
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.
66+
print(plotly.__version__) # Make sure version is correct
67+
fig = go.Figure(data=go.Scatter(x=[1, 2, 3, 4], y=[1, 3, 2, 4]))
68+
fig.show() # Figure should render in notebook
69+
```
4170

42-
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`):
71+
Code for testing `go.FigureWidget()`:
72+
```python
73+
import plotly
74+
import plotly.graph_objects as go
4375

44-
- `tar xzf output.tgz`
45-
- `pip uninstall plotly`
46-
- `conda uninstall plotly` (just in case!)
47-
- `pip install path/to/output/dist/plotly-X.Y.X-py3-none-any.whl`
76+
print(plotly.__version__) # Make sure version is correct
77+
fig = go.Figure(data=go.Scatter(x=[1, 2, 3, 4], y=[1, 3, 2, 4]))
78+
figure_widget = go.FigureWidget(fig)
79+
figure_widget # Figure should render in notebook
80+
```
4881

49-
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.
82+
Once these are verified working, you can move on to publishing the release.
5083

51-
### Publishing
84+
### Merge the release PR and make a Github release
5285

53-
Once you're satisfied that things render in Lab and Notebook in Widget and regular mode,
54-
you can publish the artifacts. **You will need special credentials from Plotly leadership to do this.**.
86+
- Merge the pull request you created above into `main`
87+
- Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
88+
- Enter the `vX.Y.Z` tag you created already above and make "Release title" the same string as the tag.
89+
- Copy the changelog section for this version into "Describe this release"
90+
- Upload the build artifacts downloaded in the previous step (`.tar` and `.whl`)
5591

92+
### Publishing to PyPI
93+
94+
The final step is to publish the release to PyPI. **You will need special permissions from Plotly leadership to do this.**.
95+
96+
You must install first install [Twine](https://pypi.org/project/twine/) (`pip install twine`) if not already installed.
5697

5798
Publishing to PyPI:
5899
```bash
59100
(plotly_dev) $ cd path/to/output
60101
(plotly_dev) $ twine upload plotly-X.Y.Z*
61102
```
62103

63-
### Merge the PR and make a Release
64-
65-
1. Merge the pull request you created above into `main`
66-
2. Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
67-
3. Enter the `vX.Y.Z` tag you created already above and make "Release title" the same string as the tag.
68-
4. Copy the changelog section for this version as the "Describe this release"
104+
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.
69105

70106
### Update documentation site
71107

0 commit comments

Comments
 (0)