Release 3.1.1 (#1096)

* Updated CHANGELOG and README
* Added release process to contributing.md

Author: jonmmease

CHANGELOG.md

@@ -2,16 +2,67 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.1.1] - 2018-08-10
+This release is a minor bug-fix update to version 3.1.0
+
+### JupyterLab Versions
+For use with JupyterLab, the following versions of the following packages
+must be installed:
+
+ - Python Packages
+   - plotly==3.1.1
+   - ipywidgets>=7.2
+   - notebook>=5.3
+   - jupyterlab==0.33
+   
+ - JupyterLab Extensions
+   - [email protected]
+   - @jupyter-widgets/jupyterlab-manager@0.36
+   - @jupyterlab/plotly-extension@0.16
+
+### Updated
+ - Updated plotly.js to version 1.39.4.
+   - This is a bug-fix release of plotly.js
+   - See [the plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#1394----2018-08-02) for more information
+
+### Fixed
+ - Fixed error in validation of configkeys
+   [plotly/plotly.js#1065](https://github.com/plotly/plotly.py/pull/1065)
+ - Fixed error in presentation of named colorscales
+   [plotly/plotly.js#1089](https://github.com/plotly/plotly.py/pull/1089)
+ - Fixed numerical precision error when using `plotly.tools.make_subplots`
+   to create figures with a large number of subplots
+   [plotly/plotly.js#1091](https://github.com/plotly/plotly.py/pull/1091)
+ - Fixed problem that prevented the use of the `.update` method to initialize
+   an array property (e.g. `layout.shapes`)
+   [plotly/plotly.js#1091](https://github.com/plotly/plotly.py/pull/1092)
+ - Fixed `FigureWidget` problem causing scroll zoom on 3D plots to stutter
+   [plotly/plotly.js#1094](https://github.com/plotly/plotly.py/pull/1094) 
+ - Fixed invalid `tickmode` property in `matplotlylib`
+   [plotly/plotly.js#1101](https://github.com/plotly/plotly.py/pull/1101)
+
 ## [3.1.0] - 2018-07-20
 
-### JupyterLab plotlywidget version: 0.2.0
-Please upgrade the Jupyterlab `plotlywidget` extension to version 0.2.0
-(See README for instructions)
+### JupyterLab Versions
+For use with JupyterLab, the following versions of the following packages
+must be installed. See [README.md](README.md) for instructions.
 
-### Plotly.js version: 1.39.2
-See [Plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md) for
-full list of changes. Select highlights are listed below. 
+ - Python Packages
+   - plotly==3.1.0
+   - ipywidgets>=7.2
+   - notebook>=5.3
+   - jupyterlab==0.32.1
+   
+ - JupyterLab Extensions
+   - [email protected]
+   - @jupyter-widgets/jupyterlab-manager@0.35
+   - @jupyterlab/plotly-extension@0.16
 
+### Updated
+ - Updated Plotly.js to version 1.39.2
+ - See highlights below
+ - See [the plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#1392----2018-07-16) for more information.
+   
 ### Added
  - Added 3D streamtube traces
    [plotly/plotly.js#2658](https://github.com/plotly/plotly.js/pull/2658)

README.md

@@ -29,7 +29,7 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
 ## Installation of plotly.py Version 3
 To install plotly.py and enable Jupyter or Jupyter Lab support, run:
 ```
-pip install plotly==3.1.0
+pip install plotly==3.1.1rc1
 pip install "notebook>=5.3" "ipywidgets>=7.2"  # only necessary for Jupyter Notebook environments
 ```
 
@@ -43,11 +43,25 @@ jupyter nbextension enable --py plotlywidget --sys-prefix
 In addition, to add JupyterLab support run the following commands
 
 ```
-pip install jupyterlab==0.32.1
+pip install jupyterlab==0.33
+
+# Avoid "JavaScript heap out of memory" errors during extension installation
+# (OS X/Linux)
 export NODE_OPTIONS=--max-old-space-size=4096
-jupyter labextension install @jupyter-widgets/[email protected] # install the Jupyter widgets extension
-jupyter labextension install [email protected]  # FigureWidget support
-jupyter labextension install @jupyterlab/[email protected]  # offline iplot support
+# (Windows)
+set NODE_OPTIONS=--max-old-space-size=4096
+
+# Jupyter widgets extension
+jupyter labextension install @jupyter-widgets/[email protected] --no-build
+
+# FigureWidget support
+jupyter labextension install [email protected]  --no-build
+
+# offline iplot support
+jupyter labextension install @jupyterlab/[email protected]  --no-build
+
+# Build extensions (must be done to activate extensions since --no-build is used above)
+jupyter lab build
 ```
 
 If you're migrating from plotly.py version 2, please check out the [migration guide](migration-guide.md)

contributing.md

@@ -215,18 +215,153 @@ When you write a new test anywhere under the `tests` directory, if your PR gets
 
 Test accounts include: `PythonTest`, `PlotlyImageTest`, and  `PlotlyStageTest`. 
 
-#### Publishing to Pip
+### Release process
+
+This is the release process for releasing `plotly.py` version `X.Y.Z` with
+`plotlywidget` version `A.B.C`.
+
+Note: The `plotlywidget` instructions must be followed if any change
+has been made in the `js/` 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
+
+#### Bump to release candidate version
+Next increment the version of `plotly.py` to `X.Y.Zrc1`, and the version of
+`plotlywidget` to `A.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`.
+
+ - `plotly/version.py`:
+   + Update `__version__` to `X.Y.Zrc1`
+   + Update `__frontend_version__` to `^A.B.C-rc.1` (Note the `^` prefix)
+ - `js/package.json`
+   + Update `"version"` to `A.B.C-rc.1`
+ 
+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.
+
+#### Finalize changelog
+Review the contents of `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.
+
+#### Publish release candidate to PyPI
+To upload to PyPI you'll also need to have `twine` installed:
+```bash
+(plotly.py) $ pip install twine
+```
+
+And, you'll need the credentials file `~/.pypirc`. Request access from
+@theengineear and @chriddyp. Then, from inside the repository:
+
+```bash
+(plotly.py) $ git checkout release_X.Y.Z
+(plotly.py) $ git stash
+(plotly.py) $ python setup.py sdist bdist_wheel
+(plotly.py) $ twine upload dist/plotly-X.Y.Zrc1*
+```
+
+#### Publish release candidate of `plotlywidget` to NPM
+Now, publish the release candidate of the `plotlywidget` NPM package.
+
+```bash
+cd ./js
+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.
 
-You'll need the credentials file `~/.pypirc`. Request access from @theengineear and @chriddyp. Then, from inside the repository:
+#### 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,
+replacing `X.Y.Z` with `X.Y.Zrc1` and `A.B.C` with `A.B.C-rc.1`.
+
+In particular 
+ - `pip install plotly==X.Y.Z` -> `pip install plotly==X.Y.Zrc1`
+ - `jupyter labextension install [email protected]` ->
+    `jupyter labextension install [email protected]`
+
+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 versions
+When no problems are identified in the release candidate, remove the
+release candidate suffix from the following version strings:
+ 
+ - `plotly/version.py`:
+   + Update `__version__` to `X.Y.Z`
+   + Update `__frontend_version__` to `^A.B.C` (Note the `^` prefix)
+ - `js/package.json`
+   + Update `"version"` to `A.B.C`
+
+#### Merge release into master
+Make sure the integration tests are passing on the release branch, then merge
+it into master on GitHub.
+
+Update your local master, tag this merge commit as `vX.Y.Z`
+(e.g. `v3.1.1`), and push the tag.
 
 ```bash
 (plotly.py) $ git checkout master
 (plotly.py) $ git stash
 (plotly.py) $ git pull origin master
-(plotly.py) $ python setup.py sdist upload # upload to pip
+(plotly.py) $ git tag vX.Y.Z
+(plotly.py) $ git push origin vX.Y.Z
 ```
 
-After it has uploaded, move to another directly and double+triple check that you are able to upgrade ok:
+#### Publishing to Pip
+
+Publish the final version to PyPI
+
+```bash
+(plotly.py) $ python setup.py sdist bdist_wheel
+(plotly.py) $ twine upload dist/plotly-X.Y.Z*
+```
+
+After it has uploaded, move to another environment and double+triple check that you are able to upgrade ok:
 ```bash
 $ pip install plotly --upgrade
 ```
@@ -236,11 +371,16 @@ And ask one of your friends to do it too. Our tests should catch any issues, but
 <3 Team Plotly
 
 #### Publish widget library to npm
+Finally, publish the final version of the widget library to npm with:
 
 ```bash
 cd ./js
 npm publish --access public
 ```
 
+#### Post announcement
+Post a simple announcement to the Plotly Python forum, with links to the
+README installation instructions and to the CHANGELOG.
+
 # 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](https://github.com/plotly/plotly.py/blob/master/plotly/figure_factory/README.md) to learn how.

js/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "plotlywidget",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The plotly.py ipywidgets library",
   "author": "The plotly.py team",
   "license": "MIT",

js/package.json

@@ -1,5 +1,5 @@
-__version__ = '3.1.0'
-__frontend_version__ = '^0.2.0'
+__version__ = '3.1.1'
+__frontend_version__ = '^0.2.1'
 
 
 def stable_semver():

plotly/version.py

@@ -1,2 +1,5 @@
 [metadata]
-description-file = README.rst
+description-file = README.rst
+
+[bdist_wheel]
+universal=1