From 37b9d56f97a13a40039e81bd091ce061259fe19c Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Tue, 17 Mar 2020 10:28:41 -0400 Subject: [PATCH 1/5] update --- contributing.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/contributing.md b/contributing.md index f4bba084293..8924e44ac0a 100644 --- a/contributing.md +++ b/contributing.md @@ -1,11 +1,14 @@ # Contributing -Thank you for contributing to plotly.py! +Thank you for contributing to plotly.py! We are actively looking for +diverse contributors. ## Code of Conduct Check out the [Code of Conduct](CODE_OF_CONDUCT.md). Don't tl:dr; it, but the general idea is to be nice. +## How to start contributing? + ## Have a Bug Report? Open an issue! Go to https://github.com/plotly/plotly.py/issues. It's possible that your issue was already addressed. If it wasn't, open it. We also accept PRs; take a look at the steps below for instructions on how to do this. From 9aea70dde6639be150aaba25daf1865fe8a45565 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Wed, 18 Mar 2020 14:58:22 -0400 Subject: [PATCH 2/5] updated contributing notes --- README.md | 14 +- contributing.md | 469 ++++++++++-------------------------------------- release.md | 364 +++++++++++++++++++++++++++++++++++++ 3 files changed, 470 insertions(+), 377 deletions(-) create mode 100644 release.md diff --git a/README.md b/README.md index 7cbb16a4f3d..90b55728a98 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,14 @@ + + User forum + + + + + + PyPI Downloads @@ -45,7 +53,7 @@ Read about what's new in [plotly.py v4](https://medium.com/plotly/plotly-py-4-0- ## Overview -[plotly.py](https://plot.ly/d3-js-for-python-and-pandas-charts/) is an interactive, open-source, and browser-based graphing library for Python :sparkles: +[plotly.py](https://plot.ly/python) is an interactive, open-source, and browser-based graphing library for Python :sparkles: Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is a high-level, declarative charting library. plotly.js ships with over 30 chart types, including scientific charts, 3D graphs, statistical charts, SVG maps, financial charts, and more. @@ -61,12 +69,12 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is --- - [Online Documentation](https://plot.ly/python) -- [Contributing](contributing.md) +- [Contributing to plotly](contributing.md) - [Changelog](CHANGELOG.md) - [Code of Conduct](CODE_OF_CONDUCT.md) - [Version 4 Migration Guide](https://plot.ly/python/next/v4-migration/) - [New! Announcing Dash 1.0](https://medium.com/plotly/welcoming-dash-1-0-0-f3af4b84bae) -- [Community](https://community.plot.ly/c/api/python) +- [Community forum](https://community.plot.ly/c/api/python) --- diff --git a/contributing.md b/contributing.md index 8924e44ac0a..38839255c68 100644 --- a/contributing.md +++ b/contributing.md @@ -1,26 +1,105 @@ # Contributing Thank you for contributing to plotly.py! We are actively looking for -diverse contributors. +diverse contributors, with diverse background and skills. -## Code of Conduct +This guide start by a general description of the different ways to contribute +to plotly.py, then we explain some technical aspects of preparing your +contribution. -Check out the [Code of Conduct](CODE_OF_CONDUCT.md). Don't tl:dr; it, but the general idea is to be nice. +## Code of Conduct -## How to start contributing? +Please check out the [Code of Conduct](CODE_OF_CONDUCT.md). Don't tl:dr; it, +but the general idea is to be nice. + +## What are the different ways to contribute? + +There are many ways to contribute to plotly.py. It helps to understand first +the structure of the code and of the repository. + +- the `codegen` (package in `packages/python/plotly/codegen`): all the code + inside `plotly.graph_objects` is generated from the plotly javascript API + (the "schema"). The `codegen` package is where the code generation is done. + Most of the codegen code concerns the generation of docstrings. Traces and + Layout classes have a direct correspondence with their Javascript + counterpart. Additional methods are defined for the `Figure` object, such as + `update_layout`, `add_trace`, etc. + +- the `plotly.express` package (usually imported as `px`) is a high-level + functional API. Its code is in `packages/python/plotly/express`. Most + functions of `plotly.express` call the internal `_make_figure` function + in `_core.py`. More generally, the internals of `px` consist of general + functions taking care of building the figure (defining subplots, traces + or frames, for example), with special cases for different traces handled + within these functions. There is also subsequent code reuse for `px` + docstrings, in particular for documenting parameters. + +- the `plotly.figure_factory` module provides Python "recipes" for building + advanced visualizations, such as Gantt charts, annotated heatmaps, etc. + Figure factories are one of the easiest entry points into plotly.py, since + they consist of Python-only code, with standalone, well-separated functions. + However, please note that some of the figure factories become less relevant + as we are introducing more features into `plotly.express`. Some issues in the + tracker are labeled "figure_factory" and can be good issues to work on. More + instructions on figure factories are found + [here](packages/python/plotly/plotly/figure_factory/README.md). + +- other pure-Python submodules are: `plotly.io` (low-level interface for + displaying, reading and writing figures), `plotly.subplots` (helper function + for layout of multi-plot figures) + +- tests are found in `packages/python/plotly/plotly/tests`. Different + directories correspond to different test jobs (with different dependency sets) + run in continuous integration. These jobs are configured in + `packages/python/plotly/tox.ini`, which itself is used in the Circle CI + configuration file `.circleci/config.yml`. More is explained about tests + in the following "Technical aspects" section. + +- the **documentation** is part of this repository. Its structure and some + explanations are described [here](doc/README.md). The documentation, in + particular example-based tutorials, is a great place to start contributing. + The contribution process is also more lightweight, since you can modify + tutorial notebooks without setting up an environment, etc. + We maintain a wishlist of examples to add on + https://github.com/plotly/plotly.py/issues/1965. If you have writing skills, + the wording of existing examples can also be improved in places. + +Contributing code or documentation are not the only way to contribute! You can +also contribute to the project by + +- reporting bugs (see below). + +- submitting feature requests (maybe we'll convince you to contribute it as a + pull request!). + +- helping other users on the [community forum](https://community.plot.ly/). + Join the list of [nice people](https://community.plot.ly/u) helping other + plotly users :-). + +We also recommend reading the great +[how to contribute to open source](https://opensource.guide/how-to-contribute/) +guide. ## Have a Bug Report? -Open an issue! Go to https://github.com/plotly/plotly.py/issues. It's possible that your issue was already addressed. If it wasn't, open it. We also accept PRs; take a look at the steps below for instructions on how to do this. +Open an issue! Go to https://github.com/plotly/plotly.py/issues. It's possible that your issue was already addressed. If it wasn't, open it. We also accept pull requests; take a look at the steps below for instructions on how to do this. ## Have Questions about Plotly? -Check out our Support App: https://support.plot.ly/libraries/python or Community Forum: https://community.plot.ly/. +Check out our Community Forum: https://community.plot.ly/. ## Want to improve the plotly documentation? Thank you! Instructions on how to contribute to the documentation are given [here](doc/contributing.md). Please also read the next section if you need to setup a development environment. +## How to contribute - Technical Aspects + +Below we explain the technical aspects of contributing. It is not strictly necessary to follow all points (for example, you will not write tests when writing documentation, most of the time), but we want to make sure that you know how to deal with most cases. + +Note that if you are modifying a single documentation page, you can do it +directly on Github by clicking on the "Edit this page on GitHub" link, without +cloning the repository. + ## Setup a Development Environment ### Fork, Clone, Setup Your Version of the Plotly Python API @@ -34,6 +113,9 @@ git clone https://github.com/your_github_username/plotly.py.git cd plotly.py ``` +Note: if you're just getting started with git, there exist great resources to +learn and become confident about git, like http://try.github.io/. + ### Create a virtual environment for plotly development You can use either [conda][conda-env] or [virtualenv][virtualenv] to create a virtual environment for plotly development, e.g. @@ -57,6 +139,10 @@ conda activate plotly-dev $ pip install -e packages/python/chart-studio/ $ pip install -e packages/python/plotly-geo/ +This will ensure that the installed packages links to your local development +directory, meaning that all changes you make reflect directly in your +environment (don't forget to restart the Jupyter kernel though!). + ### ipywidgets development install Run the following commands in your virtual environment to use the @@ -71,6 +157,7 @@ To make plotly plots show up in JupyterLab, you also need to [install the plotly [plotly-jl]: https://plot.ly/python/getting-started/#jupyterlab-support-python-35 ### Configure black code formatting + This repo uses the [Black](https://black.readthedocs.io/en/stable/) code formatter, and the [pre-commit](https://pre-commit.com/) library to manage a git commit hook to run Black prior to each commit. Both pre-commit and black are included in the @@ -109,7 +196,8 @@ git checkout -b my-dev-branch ### Pull Request When Ready -Once you've made your changes (and hopefully written some tests...), make that pull request! +Once you've made your changes (and hopefully written some tests, see below for more about testing...), +make that pull request! ## Update to a new version of Plotly.js @@ -215,370 +303,3 @@ You're *strongly* encouraged to write tests that check your added functionality. When you write a new test anywhere under the `tests` directory, if your PR gets accepted, that test will run in a virtual machine to ensure that future changes don't break your contributions! Test accounts include: `PythonTest`, `PlotlyImageTest`, and `PlotlyStageTest`. - -## Release process - plotly package - -This is the release process for releasing `plotly.py` version `X.Y.Z` with -`plotlywidget`/`jupyterlab-plotly` version `A.B.C`. - -Note: The `plotlywidget` instructions must be followed if any change -has been made in the `packages/javascript` directory source code, OR if the version of -plotly.js has been updated. If neither of these is the case, there's no need -to increment the `plotlywidget` version or to publish a new version to npm. - -### Create a release branch -After all of the functionality for the release has been merged into master, -create a branch named `release_X.Y.Z`. This branch will become the -final version - -### Finalize changelog -Review the contents of `packages/python/plotly/CHANGELOG.md`. We try to follow -the [keepachangelog](https://keepachangelog.com/en/1.0.0/) guidelines. -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 -been updated, include this as the first `Updated` entry. Call out any -noteable changes as sub-bullets (new trace types in particular), and provide -a link to the plotly.js CHANGELOG. - -As the first entry in the changelog, include a `JupyterLab Versions` section. -Here, document the versions of `plotlywidget`, -`@jupyter-widgets/jupyterlab-manager`, `jupyterlab`, and -`@jupyterlab/plotly-extension` that are known to be compatible with this -version of `plotly.py`. - -Note: Use the official (not release candidate) versions in the CHANGELOG. - -### Update README.md installation instructions - -Update the installation instructions in the README to the new versions of all -of the dependencies. Use the release candidate versions, this way we can point -people to the README of the `release_X.Y.Z` as the instructions for trying out -the release candidate. - -Note that the conda installation instructions must include -"-c plotly/lable/test" rather than "-c plotly" in order to install the -release candidate version. - -Update the `doc/python/getting-started.md` file with the same version numbers. - -Commit Changelog, README and getting-started updates. - -### Bump to release candidate version - 1) Manually update the plotlywidget version to `A.B.C-rc.1` in the files -specified below. - - - `packages/python/plotly/plotly/_widget_version.py`: - + Update `__frontend_version__` to `^A.B.C-rc.1` (Note the `^` prefix) - - `packages/javascript/plotlywidget/package.json` - + Update `"version"` to `A.B.C-rc.1` - + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` - + Run `rm -rf node_modules && npm install && npm run build` - - `packages/javascript/jupyterlab-plotly/package.json` - + Update `"version"` to `A.B.C-rc.1` - + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` - + Run `rm -rf node_modules && npm install && npm run build` - - 2) Commit the changes - - 3) Tag this commit on the release branch as `vX.Y.Zrc1` and `widget-vA.B.C-rc.1` - -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`. - -Publishing `plotly.py` and `plotlywidget` 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. - -### Publish release candidate to PyPI -To upload to PyPI you'll also need to have `twine` installed: -```bash -(plotly_dev) $ pip install twine -``` - -And, you'll need the credentials file `~/.pypirc`. Request access from -@jonmmease and @chriddyp. 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 dist/*dirty* -(plotly_dev) $ twine upload dist/plotly-X.Y.Zrc1* -``` - -Note: this will intentionally fail if your current git tree is dirty, because we want the tag -to reflect what is being released, and the version number comes from the tag and the dirty-state. - - -### Publish release candidate of `plotlywidget` and `jupyterlab-plotly` to NPM -Now, publish the release candidate of the `plotlywidget` NPM package. - -```bash -cd ./packages/javascript/plotlywidget -npm run build && npm publish --access public --tag next -``` - -The `--tag next` part ensures that users won't install this version unless -they explicitly ask for the version or for the version wtih the `next` tag. - -Do the same in the `jupyterlab-plotly` directory. - -### 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. - -```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 /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. - -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. - -### Finalize CHANGELOG and README -Update CHANGELOG with release date and update README with final versions. - -In the conda installation instructions, be sure to change the -"-c plotly/label/test" argument to "-c plotly" - -Update the doc/python/getting-started.md file with the same version numbers. - -Commit Changelog, README and getting-started updates. - -### Finalize versions -When no problems are identified in the release candidate, remove the -release candidate suffix from the following version strings: - - - `plotly/_widget_version.py`: - + Update `__frontend_version__` to `^A.B.C` (Note the `^` prefix) - - `packages/javascript/plotlywidget/package.json` - + Update `"version"` to `A.B.C` - + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` - + Run `rm -rf node_modules && npm install && npm run build` - - `packages/javascript/jupyterlab-plotly/package.json` - + Update `"version"` to `A.B.C` - + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` - + Run `rm -rf node_modules && npm install && npm run build` - - Run `git diff` and ensure that only the files you modified and the build artifacts have changed - - Ensure that the diff in `package-lock.json` seems sane - - Commit and push to the release branch. - -### Merge release into master -Make sure the integration tests are passing on the release branch, then merge -it into master on GitHub. - -Make sure tests also pass on master, then update your local master, -tag this merge commit as `vX.Y.Z` (e.g. `v3.1.1`) and `widget-vA.B.C` - -push the tag. - -```bash -(plotly_dev) $ git checkout master -(plotly_dev) $ git stash -(plotly_dev) $ git pull origin master -(plotly_dev) $ git tag vX.Y.Z -(plotly_dev) $ git push origin vX.Y.Z -(plotly_dev) $ git tag widget-vA.B.C -(plotly_dev) $ git push origin widget-vA.B.C -``` - -### Publishing to PYPI - -Publish the final version to PyPI - -```bash -(plotly_dev) $ cd packages/python/plotly -(plotly_dev) $ rm -rf dist -(plotly_dev) $ python setup.py sdist bdist_wheel -(plotly_dev) $ rm dist/*dirty* -(plotly_dev) $ twine upload dist/plotly-X.Y.Z* -``` - -Note: this will intentionally fail if your current git tree is dirty, because we want the tag -to reflect what is being released, and the version number comes from the tag and the dirty-state. - -After it has uploaded, move to another environment and double+triple check that you are able to upgrade ok: -```bash -$ pip install plotly --upgrade -``` - -And ask one of your friends to do it too. Our tests should catch any issues, but you never know. - -<3 Team Plotly - -### Publish widget library to npm -Finally, publish the final version of the widget library to npm with: - -```bash -cd packages/javascript/jupyterlab-plotly -npm run build && npm publish --access public -cd packages/javascript/plotlywidget -npm run build && npm publish --access public -``` - -### Publishing to the plotly conda channel -Follow the anaconda upload instructions as described for the release candidate -above, except: - - - Do not include the `--label test` argument when uploading - -``` -$ anaconda upload /path/to/anaconda3/conda-bld/noarch/plotly-*.tar.bz2 -``` - -### Add GitHub Release entry -Go to https://github.com/plotly/plotly.py/releases and "Draft a new release" - -Enter the vX.Y.Z tag - -Make "Release title" the same string as the tag. - -Copy changelog section for this version as the "Describe this release" - -### Upgrade doc requirements and API doc - -Files to be updated: -- `doc/apidoc/conf.py` with new version number -- `doc/requirements.txt` -- `binder/requirements.txt` - -### Synchronize master and doc-prod branches - -doc-prod should already have been merged on a regular basis into master, but -start doing it first. Then merge master into doc-prod to deploy the doc related -to features in the release. - -### Post announcement -Post a simple announcement to the Plotly Python forum, with links to the -README installation instructions and to the CHANGELOG. - -## Release process - plotly-geo package -The `plotly-geo` package contains the shape file resources used by plotly.py. -These files are relatively large and change infrequently so it is useful -to release them in a separate package. - -### Update version -Update the version of the `plotly-geo` package in -`packages/python/plotly-geo/setup.py`. - -This version is not intended to match the version of plotly.py. - -### Update CHANGELOG -Add a new entry to the CHANGELOG at `packages/python/plotly-geo/CHANGELOG.md` -and commit the changes. - -### Tag Release -Create a new tag for the release - -```bash -(plotly_dev) $ git checkout master -(plotly_dev) $ git stash -(plotly_dev) $ git pull origin master -(plotly_dev) $ git tag plotly-geo-vX.Y.Z -(plotly_dev) $ git push origin plotly-geo-vX.Y.Z -``` - -### Publishing to PYPI -Publish the final version to PyPI - -```bash -(plotly_dev) $ cd packages/python/plotly-geo -(plotly_dev) $ python setup.py sdist bdist_wheel -(plotly_dev) $ twine upload dist/plotly-geo-X.Y.Z.tar.gz -(plotly_dev) $ twine upload dist/plotly_geo-X.Y.Z-py3-none-any.whl -``` - -### Publish to plotly anaconda channel -From `packages/python/plotly-geo`, build the conda packge -```bash -(plotly_dev) $ conda build recipe/ -``` - -Then upload to the plotly anaconda channel as described above - -## Release process - chart-studio package -The `chart-studio` package contains the utilities for interacting with -Chart Studio (both Cloud or On-Prem). - -### Update version -Update the version of the `chart-studio` package in -`packages/python/chart-studio/setup.py`. - -This version is not intended to match the version of plotly.py. - -### Update CHANGELOG -Add a new entry to the CHANGELOG at `packages/python/chart-studio/CHANGELOG.md` -and commit the changes. - -### Tag Release -Create a new tag for the release - -```bash -(plotly_dev) $ git checkout master -(plotly_dev) $ git stash -(plotly_dev) $ git pull origin master -(plotly_dev) $ git tag chart-studio-vX.Y.Z -(plotly_dev) $ git push origin chart-studio-vX.Y.Z -``` - -### Publishing to PYPI -Publish the final version to PyPI - -```bash -(plotly_dev) $ cd packages/python/chart-studio -(plotly_dev) $ python setup.py sdist bdist_wheel -(plotly_dev) $ twine upload dist/chart-studio-X.Y.Z.tar.gz -(plotly_dev) $ twine upload dist/chart_studio-X.Y.Z-py3-none-any.whl -``` - -### Publish to plotly anaconda channel -From `packages/python/plotly-geo`, build the conda packge -```bash -(plotly_dev) $ conda build recipe/ -``` - -Then upload to the plotly anaconda channel as described above - -## Contributing to the Figure Factories -If you are interested in contributing to the ever-growing Plotly figure factory library in Python, check out the [documentation][ff-home] to learn how. - -[ff-home]: packages/python/plotly/plotly/figure_factory/README.md diff --git a/release.md b/release.md new file mode 100644 index 00000000000..e76d2d7b19f --- /dev/null +++ b/release.md @@ -0,0 +1,364 @@ + +# How to release plotly packages + +## Release process - plotly package + +This is the release process for releasing `plotly.py` version `X.Y.Z` with +`plotlywidget`/`jupyterlab-plotly` version `A.B.C`. + +Note: The `plotlywidget` instructions must be followed if any change +has been made in the `packages/javascript` directory source code, OR if the version of +plotly.js has been updated. If neither of these is the case, there's no need +to increment the `plotlywidget` version or to publish a new version to npm. + +### Create a release branch +After all of the functionality for the release has been merged into master, +create a branch named `release_X.Y.Z`. This branch will become the +final version + +### Finalize changelog +Review the contents of `packages/python/plotly/CHANGELOG.md`. We try to follow +the [keepachangelog](https://keepachangelog.com/en/1.0.0/) guidelines. +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 +been updated, include this as the first `Updated` entry. Call out any +noteable changes as sub-bullets (new trace types in particular), and provide +a link to the plotly.js CHANGELOG. + +As the first entry in the changelog, include a `JupyterLab Versions` section. +Here, document the versions of `plotlywidget`, +`@jupyter-widgets/jupyterlab-manager`, `jupyterlab`, and +`@jupyterlab/plotly-extension` that are known to be compatible with this +version of `plotly.py`. + +Note: Use the official (not release candidate) versions in the CHANGELOG. + +### Update README.md installation instructions + +Update the installation instructions in the README to the new versions of all +of the dependencies. Use the release candidate versions, this way we can point +people to the README of the `release_X.Y.Z` as the instructions for trying out +the release candidate. + +Note that the conda installation instructions must include +"-c plotly/lable/test" rather than "-c plotly" in order to install the +release candidate version. + +Update the `doc/python/getting-started.md` file with the same version numbers. + +Commit Changelog, README and getting-started updates. + +### Bump to release candidate version + 1) Manually update the plotlywidget version to `A.B.C-rc.1` in the files +specified below. + + - `packages/python/plotly/plotly/_widget_version.py`: + + Update `__frontend_version__` to `^A.B.C-rc.1` (Note the `^` prefix) + - `packages/javascript/plotlywidget/package.json` + + Update `"version"` to `A.B.C-rc.1` + + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` + + Run `rm -rf node_modules && npm install && npm run build` + - `packages/javascript/jupyterlab-plotly/package.json` + + Update `"version"` to `A.B.C-rc.1` + + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` + + Run `rm -rf node_modules && npm install && npm run build` + + 2) Commit the changes + + 3) Tag this commit on the release branch as `vX.Y.Zrc1` and `widget-vA.B.C-rc.1` + +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`. + +Publishing `plotly.py` and `plotlywidget` 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. + +### Publish release candidate to PyPI +To upload to PyPI you'll also need to have `twine` installed: +```bash +(plotly_dev) $ pip install twine +``` + +And, you'll need the credentials file `~/.pypirc`. Request access from +@jonmmease and @chriddyp. 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 dist/*dirty* +(plotly_dev) $ twine upload dist/plotly-X.Y.Zrc1* +``` + +Note: this will intentionally fail if your current git tree is dirty, because we want the tag +to reflect what is being released, and the version number comes from the tag and the dirty-state. + + +### Publish release candidate of `plotlywidget` and `jupyterlab-plotly` to NPM +Now, publish the release candidate of the `plotlywidget` NPM package. + +```bash +cd ./packages/javascript/plotlywidget +npm run build && npm publish --access public --tag next +``` + +The `--tag next` part ensures that users won't install this version unless +they explicitly ask for the version or for the version wtih the `next` tag. + +Do the same in the `jupyterlab-plotly` directory. + +### 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. + +```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 /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. + +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. + +### Finalize CHANGELOG and README +Update CHANGELOG with release date and update README with final versions. + +In the conda installation instructions, be sure to change the +"-c plotly/label/test" argument to "-c plotly" + +Update the doc/python/getting-started.md file with the same version numbers. + +Commit Changelog, README and getting-started updates. + +### Finalize versions +When no problems are identified in the release candidate, remove the +release candidate suffix from the following version strings: + + - `plotly/_widget_version.py`: + + Update `__frontend_version__` to `^A.B.C` (Note the `^` prefix) + - `packages/javascript/plotlywidget/package.json` + + Update `"version"` to `A.B.C` + + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` + + Run `rm -rf node_modules && npm install && npm run build` + - `packages/javascript/jupyterlab-plotly/package.json` + + Update `"version"` to `A.B.C` + + Ensure you're using `node` version 8 and `npm` version 6 to minimize diffs to `package-lock.json` + + Run `rm -rf node_modules && npm install && npm run build` + - Run `git diff` and ensure that only the files you modified and the build artifacts have changed + - Ensure that the diff in `package-lock.json` seems sane + - Commit and push to the release branch. + +### Merge release into master +Make sure the integration tests are passing on the release branch, then merge +it into master on GitHub. + +Make sure tests also pass on master, then update your local master, +tag this merge commit as `vX.Y.Z` (e.g. `v3.1.1`) and `widget-vA.B.C` + +push the tag. + +```bash +(plotly_dev) $ git checkout master +(plotly_dev) $ git stash +(plotly_dev) $ git pull origin master +(plotly_dev) $ git tag vX.Y.Z +(plotly_dev) $ git push origin vX.Y.Z +(plotly_dev) $ git tag widget-vA.B.C +(plotly_dev) $ git push origin widget-vA.B.C +``` + +### Publishing to PYPI + +Publish the final version to PyPI + +```bash +(plotly_dev) $ cd packages/python/plotly +(plotly_dev) $ rm -rf dist +(plotly_dev) $ python setup.py sdist bdist_wheel +(plotly_dev) $ rm dist/*dirty* +(plotly_dev) $ twine upload dist/plotly-X.Y.Z* +``` + +Note: this will intentionally fail if your current git tree is dirty, because we want the tag +to reflect what is being released, and the version number comes from the tag and the dirty-state. + +After it has uploaded, move to another environment and double+triple check that you are able to upgrade ok: +```bash +$ pip install plotly --upgrade +``` + +And ask one of your friends to do it too. Our tests should catch any issues, but you never know. + +<3 Team Plotly + +### Publish widget library to npm +Finally, publish the final version of the widget library to npm with: + +```bash +cd packages/javascript/jupyterlab-plotly +npm run build && npm publish --access public +cd packages/javascript/plotlywidget +npm run build && npm publish --access public +``` + +### Publishing to the plotly conda channel +Follow the anaconda upload instructions as described for the release candidate +above, except: + + - Do not include the `--label test` argument when uploading + +``` +$ anaconda upload /path/to/anaconda3/conda-bld/noarch/plotly-*.tar.bz2 +``` + +### Add GitHub Release entry +Go to https://github.com/plotly/plotly.py/releases and "Draft a new release" + +Enter the vX.Y.Z tag + +Make "Release title" the same string as the tag. + +Copy changelog section for this version as the "Describe this release" + +### Upgrade doc requirements and API doc + +Files to be updated: +- `doc/apidoc/conf.py` with new version number +- `doc/requirements.txt` +- `binder/requirements.txt` + +### Synchronize master and doc-prod branches + +doc-prod should already have been merged on a regular basis into master, but +start doing it first. Then merge master into doc-prod to deploy the doc related +to features in the release. + +### Post announcement +Post a simple announcement to the Plotly Python forum, with links to the +README installation instructions and to the CHANGELOG. + +## Release process - plotly-geo package +The `plotly-geo` package contains the shape file resources used by plotly.py. +These files are relatively large and change infrequently so it is useful +to release them in a separate package. + +### Update version +Update the version of the `plotly-geo` package in +`packages/python/plotly-geo/setup.py`. + +This version is not intended to match the version of plotly.py. + +### Update CHANGELOG +Add a new entry to the CHANGELOG at `packages/python/plotly-geo/CHANGELOG.md` +and commit the changes. + +### Tag Release +Create a new tag for the release + +```bash +(plotly_dev) $ git checkout master +(plotly_dev) $ git stash +(plotly_dev) $ git pull origin master +(plotly_dev) $ git tag plotly-geo-vX.Y.Z +(plotly_dev) $ git push origin plotly-geo-vX.Y.Z +``` + +### Publishing to PYPI +Publish the final version to PyPI + +```bash +(plotly_dev) $ cd packages/python/plotly-geo +(plotly_dev) $ python setup.py sdist bdist_wheel +(plotly_dev) $ twine upload dist/plotly-geo-X.Y.Z.tar.gz +(plotly_dev) $ twine upload dist/plotly_geo-X.Y.Z-py3-none-any.whl +``` + +### Publish to plotly anaconda channel +From `packages/python/plotly-geo`, build the conda packge +```bash +(plotly_dev) $ conda build recipe/ +``` + +Then upload to the plotly anaconda channel as described above + +## Release process - chart-studio package +The `chart-studio` package contains the utilities for interacting with +Chart Studio (both Cloud or On-Prem). + +### Update version +Update the version of the `chart-studio` package in +`packages/python/chart-studio/setup.py`. + +This version is not intended to match the version of plotly.py. + +### Update CHANGELOG +Add a new entry to the CHANGELOG at `packages/python/chart-studio/CHANGELOG.md` +and commit the changes. + +### Tag Release +Create a new tag for the release + +```bash +(plotly_dev) $ git checkout master +(plotly_dev) $ git stash +(plotly_dev) $ git pull origin master +(plotly_dev) $ git tag chart-studio-vX.Y.Z +(plotly_dev) $ git push origin chart-studio-vX.Y.Z +``` + +### Publishing to PYPI +Publish the final version to PyPI + +```bash +(plotly_dev) $ cd packages/python/chart-studio +(plotly_dev) $ python setup.py sdist bdist_wheel +(plotly_dev) $ twine upload dist/chart-studio-X.Y.Z.tar.gz +(plotly_dev) $ twine upload dist/chart_studio-X.Y.Z-py3-none-any.whl +``` + +### Publish to plotly anaconda channel +From `packages/python/plotly-geo`, build the conda packge +```bash +(plotly_dev) $ conda build recipe/ +``` + +Then upload to the plotly anaconda channel as described above. From 0dc596a79d88d555504a0921c7fd125dd22eb4b3 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Wed, 18 Mar 2020 15:15:19 -0400 Subject: [PATCH 3/5] code pr in template --- .github/pull_request_template.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f9fe15214d1..9047588c8fd 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,10 @@ From c6ca49b42ae35a9570ab59eb592f08e3553f78d1 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Thu, 19 Mar 2020 09:47:25 -0400 Subject: [PATCH 4/5] pinning orca --- .circleci/create_conda_optional_env.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/create_conda_optional_env.sh b/.circleci/create_conda_optional_env.sh index d1d48f7e998..78c79940828 100755 --- a/.circleci/create_conda_optional_env.sh +++ b/.circleci/create_conda_optional_env.sh @@ -19,5 +19,5 @@ if [ ! -d $HOME/miniconda/envs/circle_optional ]; then requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets # Install orca into environment - $HOME/miniconda/bin/conda install --yes -n circle_optional -c plotly plotly-orca + $HOME/miniconda/bin/conda install --yes -n circle_optional -c plotly plotly-orca=1.2.1 fi From 99f53ca7d3f7690d75a35dd9380596ddf9a6953d Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Thu, 19 Mar 2020 18:48:29 -0400 Subject: [PATCH 5/5] add doc requirement --- .github/pull_request_template.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9047588c8fd..842cffab482 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -30,5 +30,7 @@ below :-). - [ ] I have read through the [contributing notes](https://github.com/plotly/plotly.py/blob/master/contributing.md) and understand the structure of the package. In particular, if my PR modifies code of `plotly.graph_objects`, my modifications concern the `codegen` files and not generated files. - [ ] I have added tests (if submitting a new feature or correcting a bug) or modified existing tests. +- [ ] For a new feature, I have added documentation examples in an existing or + new tutorial notebook (please see the doc checklist as well). -->