Skip to content

Commit

Permalink
update release instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@nicolaskruchten
nicolaskruchten committed Jun 8, 2022
1 parent 3e7a4e3 commit d4c461a
Showing 1 changed file with 55 additions and 152 deletions.
207 changes: 55 additions & 152 deletions release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,92 +43,82 @@ Manually update the versions to `X.Y.Z` in the files specified below.
+ Update `"version"` to `X.Y.Z`
- `packages/javascript/jupyterlab-plotly/package-lock.json`
+ Update `"version"` to `X.Y.Z`
- Commit and add this specific tag which `versioneer` will pick up, and push to Github so that CI will build the release artifacts:
- Commit your changes on the branch:
+ `git commit -a -m "version changes for vX.Y.Z"`
+ `git tag vX.Y.Z`
+ `git push --atomic origin release-X.Y.Z vX.Y.Z`

### Download and check CI Artifacts
### Triggering (and Retriggering) the build

<WIP>
- Commit and add this specific tag which `versioneer` will pick up, and push to Github so that CI will build the release artifacts. This is an atomic push so that CI will read the tag on the commit:
+ `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 `master` and wait for CI to be green
- *If something goes wrong below*, you'll need to trigger the build process again after a fix. You'll need to commit your changes in the release branch, move the tag and atomically force push:
+ `git commit ....`
+ `git tag -f vX.Y.Z`
+ `git push --force --atomic origin release-X.Y.Z vX.Y.Z`

### Publishing to PyPI
### Download and QA CI Artifacts

Build and publish the final version to PyPI.
The `full_build` job in the `release_build` workflow in CircleCI produces three sets of artifacts. Download all three:

> NOTE: for some reason, this produces a broken build if `npm run build:prod` isn't '
> run once before in the `jupyterlab-plotly` directory so don't skip that step above!
1. `pypi_dist/all.tgz`
2. `conda_dist/plotly-X.Y.Z.tar.bz2`
3. `npm_dist/jupyterlab-plotly-X.Y.Z.tgz`

```bash
(plotly_dev) $ git status # make sure it's not dirty!
(plotly_dev) $ cd packages/python/plotly
(plotly_dev) $ rm -rf dist
(plotly_dev) $ python setup.py sdist bdist_wheel
(plotly_dev) $ rm -f dist/*dirty* # make sure your version is not dirty!
```
**Note: if any of the version numbers are not simply `X.Y.Z` but include some kind of git hash, then this is a dirty build and you'll need to clean up whatever is dirtying the tree and follow the instructions above to trigger the build again.** (That said, you can do QA on dirty builds, you just can't publish them.)

Here you should do some local QA:
To locally install the PyPI dist, make sure you have an environment with JupyterLab 3 installed:

```bash
(plotly_dev) $ pip uninstall plotly
(plotly_dev) $ pip install dist/plotly-X.Y.X-py2.py3-none-any.whl
```
- `tar xzf all.tgz`
- `pip uninstall plotly`
- `conda uninstall plotly` (just in case!)
- `pip install dist/plotly-X.Y.X-py2.py3-none-any.whl`

Once you're satisfied that things render in Lab and Notebook in Widget and regular mode,
you can upload to PyPI.
To locally install the Conda dist (generally do this in a different, clean environment from the one above!):

```bash
(plotly_dev) $ twine upload dist/plotly-X.Y.Z*
```
- `conda uninstally plotly`
- `pip uninstall plotly` (just in case!)
- `conda install conda_dist/plotly-X.Y.Z.tar.bz2`

It's more complicated to locally install the NPM bundle, as you'll need to have a JupyterLab 2 environment installed... Undocumented for now :see_no_evil:.

After it has uploaded, move to another environment and double+triple check that you are able to upgrade ok:
```bash
$ pip install plotly --upgrade
```
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.

And ask one of your friends to do it too. Our tests should catch any issues, but you never know.
If something is broken, you'll need to fix it and trigger the build again (see above section).

### Publish JS Extensions to NPM
### Publishing

Build and publish the final version of the extensions to NPM. We do this right away because
once we push to PyPI the README will refer to these versions.
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.**.

> NOTE: this assumes the extension is already built above so don't skip that step above!

Publishing to PyPI:
```bash
cd packages/javascript/jupyterlab-plotly
npm publish --access public
(plotly_dev) $ cd pypi_dist/dist
(plotly_dev) $ twine upload plotly-X.Y.Z*
```

### Publishing to the plotly conda channel

To publish package to the plotly anaconda channel you'll need to have the
anaconda or miniconda distribution installed, and you'll need to have the
`anaconda-client` package installed.
Publishing to NPM:

```bash
(plotly_dev) $ conda config --set anaconda_upload no
(plotly_dev) $ conda build recipe/
(plotly_dev) $ cd npm_dist
(plotly_dev) $ npm publish jupyterlab-plotly-X.Y.Z.tgz
```

Then upload artifacts to the anaconda channel by running the upload command that `conda`
provides, which looks something like this:
Publishing to `plotly` conda channel (make sure you have run `conda install anaconda-client` to get the `anaconda` command):

```
$ anaconda upload /path/to/anaconda3/conda-bld/noarch/plotly-*.tar.bz2
(plotly_dev) $ cd conda_dist
(plotly_dev) $ anaconda upload plotly-X.Y.Z.tar.bz2
```

### Push the commit and add GitHub Release entry

```bash
(plotly_dev) $ git push origin master
(plotly_dev) $ git push origin vX.Y.Z
```
### Merge the PR and make a Release

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

### Update documentation site

Expand All @@ -153,123 +143,36 @@ to features in the release.
* 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 *Candidate* process - `plotly` package

### Bump to release candidate version

1) Manually update the versions to `X.Y.Z-rc.1` in the files
specified below.

- `packages/python/plotly/plotly/_widget_version.py`:
+ Update `__frontend_version__` to `^X.Y.Z-rc.1` (Note the `^` prefix)
- `packages/javascript/jupyterlab-plotly/package.json`
+ Update `"version"` to `X.Y.Z-rc.1`
+ Ensure you're using `node` version 12 and `npm` version 6 to minimize diffs to `package-lock.json`
+ Ensure you're in a Python virtual environment with JupyterLab 3 installed
+ Run `rm -rf node_modules && npm install && npm run build:prod`

2) Commit the changes

3) Tag this commit on the release branch as `vX.Y.Zrc1`

In both cases `rc` is the semantic versioning code for Release Candidate.

The number 1 means that this is the first release candidate, this number can
be incremented if we need to publish multiple release candidates.
Note that the `npm` suffix is `-rc.1` and the PyPI suffix is `rc1`.
## Release *Candidate* process - `plotly` package and extensions

Publishing `plotly.py` and `jupyterlab-plotly` as release candidates
allows us to go through the publication process, and test that the
installed packages work properly before general users will get them by
default. It also gives us the opportunity to ask specific users to test
that their bug reports are in fact resolved before we pull the trigger
on the official release.
(rough notes for a rough/ad hoc process!)

### Publish release candidate to PyPI
It's the same process as above except that the `X.Y.Z` version has a suffix and there are special instructions below for publishing an RC: note that the `npm` suffix is `-rc.1` and the PyPI suffix is `rc1`. We also don't update the docs with RC information and we inform a limited number of stakeholders.

To upload to PyPI you'll also need to have `twine` installed:
```bash
(plotly_dev) $ pip install twine
```

And, you'll need to be a maintainer on PyPI. Then, from inside the repository:

```bash
(plotly_dev) $ cd packages/python/plotly
(plotly_dev) $ git checkout release_X.Y.Z
(plotly_dev) $ git stash
(plotly_dev) $ rm -rf dist
(plotly_dev) $ python setup.py sdist bdist_wheel
(plotly_dev) $ rm -f dist/*dirty* # make sure your version is not dirty!
```

Here you should do some local QA:

```bash
(plotly_dev) $ pip uninstall plotly
(plotly_dev) $ pip install dist/plotly-vX.Y.Zrc1-py2.py3-none-any.whl
```

Once you're satisfied that things render in Lab and Notebook in Widget and regular mode,
you can upload to PyPI.
PyPI RC (no special flags, just the `rc1` suffix):

```bash
(plotly_dev) $ twine upload dist/plotly-X.Y.Zrc1*
```

### Publish release candidate of JS Extensions to NPM

Now, publish the release candidate of the extensions to NPM.
NPM RC:

```bash
cd ./packages/javascript/jupyterlab-plotly
npm publish --access public --tag next
npm publish --access public --tag next jupyterlab-plotly.*
```

The `--tag next` part ensures that users won't install this version unless
they explicitly ask for the version or for the version with the `next` tag.

### Publish release candidate to plotly anaconda channel

To publish package to the plotly anaconda channel you'll need to have the
anaconda or miniconda distribution installed, and you'll need to have the
`anaconda-client` package installed.
Conda RC:

```bash
(plotly_dev) $ conda config --set anaconda_upload no
(plotly_dev) $ conda build recipe/
```

Next run `anaconda login` and enter the credentials for the plotly anaconda
channel.

Then upload artifacts to the anaconda channel using the test label. Using the test
label will ensure that people will only download the release candidate version
if they explicitly request it.

$ anaconda upload --label test plotly-*.tar.bz2
```
$ anaconda upload --label test /path/to/anaconda3/conda-bld/noarch/plotly-*.tar.bz2
```

Then logout with `anaconda logout`

### Manually test the release candidate

Create a fresh virtual environment (or conda environment) and install
the release candidate by following the new `README.md` instructions
(the instructions updated above to include the release candidate versions)

Run through the example notebooks at
https://github.com/jonmmease/plotly_ipywidget_notebooks using the classic
notebook and JupyterLab. Make sure `FigureWidget` objects are displayed as
plotly figures, and make sure the in-place updates and callbacks work.

If appropriate, ask users who have submitted bug reports or feature
requests that are resolved in this version to try out the release candidate.
The `--label test` part ensures that users won't install this version unless
they explicitly ask for the version or for the version with the `next` tag.

If problems are found in the release candidate, fix them on the release
branch and then publish another release candidate with the candidate number
incremented.

## Release process - `plotly-geo` package

Expand Down

0 comments on commit d4c461a

Please sign in to comment.