Merge pull request #45 from cxhernandez/release-0.2.0

Release 0.2.0

devtools/README.md

@@ -1,107 +1,77 @@
-How to release
-===================
-
-Pre-release + Github
---------------------
-- Update the `docs/whatsnew.rst` document. Use the github view that shows all the
-  commits to master since the last release to write it
-   * You can also try using [this tool](https://github.com/rmcgibbo/gh-util), which should list all
-     of the PRs that have been merged since the laster release.
-- Update the version number in `devtools/conda-recipe/meta.yaml`
-- Commit to master, and tag the
-  release on github.
-- Run git pull to pull the newly created tag locally. Versioneer depends on
-  this to get the version string right.
-
-PyPI
-----
-The next step is to add the release to the python package index.
-
-- Git pull, and make sure it pulls the recent tag.
-- Run `git clean -fdx` to clean the source directory.
-- Create the cannoncal "sdist" (source distribution) using `python setup.py sdist --formats=gztar,zip`.
-  You ran git clean, right?
-- Inspect the sdist files (they're placed in `dist/`), and make sure they look right.
-  You can try installing them into your environment with pip, unzipping or untaring them, etc.
-- Once you're satisfied that the sdist is correct, push the source to PyPI using
-  `twine upload [path to sdist files]`. This requires being registered on PyPI as a owner or maintainer
-  of the project.
-
-Immediately after creating the sdist
-------------------------------------
-- Update the version number in `devtools/conda-recipy/meta.yaml`
-  to `1.(x+1).0.dev0` per PEP440.
-- Add a new section in `docs/whatsnew.rst` and mark it "(Development)".
-- Commit to master.
-
-Conda
------
-- File a PR against [omnia-md/conda-recipes](https://github.com/omnia-md/conda-recipes) that
-  updates the recipe's version string and source URL to pull the new sdist from PyPI. Travis
-  and Appveyor will then build binary conda packages.
-
-Wheels
-------
+Developer Notes / Tools
+=======================
 
-PyPI hosts *wheels*, pre-compiled binary packages, like conda packages, for OS X and
-Windows. (At the time of this writing, they are still ironing out issues w.r.t.
-linux.) To create and upload wheels, download the sdist and unpack the (or check out
-the exact tag from git), and run `python setup.py bdist_wheel`.
+How to do a release
+-------------------
+
+### Pre-release
+
+- Tag issues and pull requests with a milestone for the particular version.
+- Use the "changelog" tag to tag pull requests that need to be recorded in `docs/changelog.rst`.
+  You've been encouraging people to update the changelog *with* their pull requests, though, right?
+- Update `docs/changelog.rst`. Change the tag from "changelog" to "changelogged".
+- Optionally create an issue about cutting the release.
+- Fix and close all open issues and PRs with the release's milestone.
+
+### Release
+
+- `git checkout master && git fetch origin && git reset --hard origin/master`
+- `git clean -fdx`
+- Update the version number in `setup.py`, change `ISRELEASED` to `True`.
+- Verify the version number in `devtools/conda-recipe/meta.yaml` is "0.0.0".
+- Add the date of release to `docs/changelog.rst`, add a blurb.
+- Commit and push to master. The commit should only include the version number changes and
+  should be given a message like "Release x.y.z".
+- Tag that commit on GitHub. For version x.y.z, the tag should be `x.y.z` (no "v" prefix)
+  and the title should be "MSMExplorer x.y" (no .z). You should copy-paste the changelog entry
+  for the GitHub release notes. Beware of the transition from `rst` to markdown. In particular,
+  you might have to change the headings from underlined to prefixed with `##`. You should
+  also delete "hard-wrap" linebreaks because GitHub will keep them in! (and you don't want
+  that). Use the preview tab.
+- The docs will build. Make sure this is successful and they are live at msmbuilder.org/msmexplorer.
+  The docs will be sent to msmbuilder.org/msmexplorer/x.y.z instead of development/ because you
+  set `ISRELEASED`. You can cancel the Travis build triggered by the "tag" because docs
+  are set to deploy only from `master`.
+- Verify that `versions.json` was updated properly.
+- Create the canonical source distribution using `python setup.py sdist --formats=gztar,zip`.
+  Inspect the files in dist/ to make sure they look right.
+- Upload to PyPI using `twine upload [path to sdist files]`.
+- File a pull request against the
+  [conda-recipes](https://github.com/omnia-md/conda-recipes) repository.
+  Use the PyPI link as the "source". Make sure the requirements match those
+  in the msmexplorer recipe in `devtools/conda-recipe`. We don't want the package
+  that gets tested with every pull request to differ from the one people actually get!
+  Conda binaries should be automatically built.
+- Make an announcement on the mailing list.
+
+### Post-release
+
+- Update the version number in `setup.py`, change `ISRELEASED` to `False`.
+- Verify the version number in `devtools/conda-recipe/meta.yaml` is "0.0.0".
+- Add a new "development" entry in `docs/changelog.rst`.
+- Commit and push to master.
+- Make sure there is a x.(y+1) milestone already created
+- Create a new x.(y+2) milestone [y is still the value of the release you just did]
+- Close the x.y milestone.
+- Update this file (`devtools/README.md`) with anything you learned or
+  changed during this release creation.
+- Open an Issue for x.(y+1) release schedule.
+
+### Point releases
+
+If you want to include a minor or important fix, you can create a point release.
+For version x.y.z, this would mean bumping `z`.
+
+- `git checkout x.y.0` (the tag)
+- `git checkout -b x.y` (make x.y branch)
+- Make a commit that updates the versions, isreleased in setup.py and conda recipe.
+  This time, change to `x.y.(z+1).dev0` instead of `x.(y+1).0.dev0`
+- `git push origin x.y -u`
+- Backport or cherry-pick the fixes you need.
+- Go through the above for creating a release. Make sure you tag
+  the commit on the x.y branch. If you don't want release notes
+  (e.g. for a really minor fix), you can create an unannotated tag.
 
-For example, to build wheels for Python 2.7, 3.4 and 3.5 on OS X, I ran
 ```
-conda env remove -y -n _build
-versions=("2.7" "3.4" "3.5")
-for v in "${versions[@]}"; do
-    conda create -y -n _build python=$v numpy cython
-    source activate _build
-    python setup.py bdist_wheel
-    source deactivate
-    conda env remove -y -n _build
-done
+vim: tw=90
 ```
-Then, if these all look good, you can upload them to PyPI with twine, as was done with the
-sdist.
-
-
-Docs Building & Hosting
-=======================
-
-After a travis build succeeds, the docs are built with sphinx and pushed to
-the msmbuilder.org amazon s3 account in the msmexplorer/ subdirectory.
-The credentials for that account are stored,
-encrypted, in the .travis.yml file.
-
-Multiple versions of the docs are hosted
-online. When a build happens on a version with ISRELEASED==False, it's put into
-the "development" folder on the S3 bucket. If ISRELEASED==True, it's put into a
-subfolder with the name of the short release. The relevant logic is in
-`devtools/travis-ci/set_doc_version.py`.
-
-
-Tools License
-=============
-Copyright (c) 2012-2016 Stanford University and the Authors
-All rights reserved.
-
-Redistribution and use of all files in this folder (devtools) and (../.travis.yml,
-../basesetup.py, ../setup.py) files in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-this list of conditions and the following disclaimer in the documentation
-and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/changelog.rst

@@ -3,15 +3,50 @@
 Changelog
 =========
 
-v0.1.0
-------------------
+v0.2.0 (September 15, 2016)
+---------------------------
 
-This is the latest stable version of MSMExplorer
+We're pleased to announce the release of MSMExplorer v0.2.0. The focus of this
+release is improving plotting reproducibility and utilities. There is also a
+major bugfix for ``plot_chord`` and ``plot_free_energy``. We encourage all
+users to update to v0.2.0.
+
+API Changes
+~~~~~~~~~~~
+
+- ``darkslategrey`` has been renamed to ``carbon`` (#41).
+- ``plot_free_energy`` now supports a ``random_state`` option (#40)
 
 New Features
 ~~~~~~~~~~~~
-+ Clustering plots: ``plot_voronoi``
-+ MSM plots: ``plot_pop_resids``, ``plot_msm_network``, ``plot_timescales``
-+ Projection plots: ``plot_free_energy``, ``plot_histogram``
-+ TPT plots: ``plot_tpaths``
-+ Misc. plots: ``plot_chord``, ``plot_trace``
+
+- ``example_datasets`` has been added. This allows example datasets to be
+  pulled from the ``msmb_data`` package (#41).
+- ``make_colormap`` has been added in ``msmexplorer.utils``. It creates a
+  linear colormap from a color palette (#40).
+- ``msme_colors`` has been added in ``msmexplorer.utils``. It allows any
+  non-native plotting functions to handle MSMExplorer color strings (#40).
+
+Improvements
+~~~~~~~~~~~~
+
+- Test coverage is greatly improved (#43)
+- ``plot_free_energy`` now produces correct 1-D free energy plots (#43).
+- ``extract_palette`` is now more robust (#40).
+- Improve example reproducibility (#40)
+- Fix path vertices problem in ``plot_chord`` (#38).
+
+
+v0.1.0 (August 30, 2016)
+------------------------
+
+This is the first stable version of MSMExplorer
+
+New Features
+~~~~~~~~~~~~
+
+- Clustering plots: ``plot_voronoi``
+- MSM plots: ``plot_pop_resids``, ``plot_msm_network``, ``plot_timescales``
+- Projection plots: ``plot_free_energy``, ``plot_histogram``
+- TPT plots: ``plot_tpaths``
+- Misc. plots: ``plot_chord``, ``plot_trace``