HOW_TO_RELEASE

How to issue an aospy release in a few easy steps

(Adapted from xarray's HOW_TO_RELEASE document)

Time required: about an hour.

 1. Ensure your master branch is synced to upstream:
       git pull upstream master
 2. Look over whats-new.rst and the docs. Make sure "What's New" is complete
    (check the date!) and add a brief summary note describing the release at the
    top.
 3. Run the full test suite one final time!
      py.test
 4. Make sure the docs are in order:
    - Build our docs locally to ensure that the build works and that
      there are no broken links.  From aospy/doc:
        make clean
        make html
        make linkcheck
    - Verify that our docs on ReadTheDocs have been building successfully by
      checking the most recent builds  tagged 'latest' at:
      https://readthedocs.org/projects/aospy/builds/.  If not, examine
      the build log to determine what neds to be fixed, and fix it.
 5. On the master branch, commit the release in git:
      git commit -a -m 'Release v0.X.Y'
 6. Tag the release:
      git tag -a v0.X.Y -m 'v0.X.Y'
 7. Build source and binary wheels for pypi:
      git clean -xdf  # this deletes all uncommited changes!
      python setup.py bdist_wheel sdist
 8. Use twine to register and upload the release on pypi. Be careful, you can't
    take this back!
      twine upload dist/aospy-0.X.Y*
    You will need to be listed as a package owner at
    https://pypi.python.org/pypi/aospy for this to work.
 9. Push your changes to master:
      git push upstream master
      git push upstream --tags
10. Update the stable branch (used by ReadTheDocs) and switch back to master:
      git checkout stable
      git rebase master
      git push upstream stable
      git checkout master
    It's OK to force push to 'stable' if necessary.
    We also update the stable branch with `git cherrypick` for documentation
    only fixes that apply the current released version.
11. Add a section for the next release (v.X.(Y+1)) to doc/whats-new.rst.
12. Commit your changes and push to master again:
      git commit -a -m 'Revert to dev version'
      git push upstream master
    You're done pushing to master!
13. Issue the release on GitHub.  Click on "Draft a new release" at
    https://github.com/spencerahill/aospy/releases. Type in the version number, but
    don't bother to describe it -- we maintain that on the docs instead.
14. Update the docs.  Login to https://readthedocs.org/projects/aospy/versions/
    and switch your new release tag (at the bottom) from "Inactive" to "Active".
    It should now build automatically.
15. Update the conda-forge/aospy-feedstock:
    - From your fork of aospy-feedstock, create a new branch:
        git pull upstream master
        git checkout -b aospy-release-v0.X.Y
    - In recipe/meta.yaml, update the {% set version = "0.X.Y" %} line
    - Since this is a new release, make sure that the 'number' is set to 0
      under the 'build' section.
    - Push the branch upstream
    - Find the new branch on https://github.com/conda-forge/aospy-feedstock/branches,
      and issue the Pull Request.
    - Once all the CI passes, merge in the PR and delete the branch.
    - Give it a few minutes, then check that the new conda-forge
      builds were successful, i.e. that they show up at the bottom of:
        conda search -c conda-forge aospy
16. Issue the release announcement!  For bug fix releases, I usually only email
    aospy@googlegroups.com.  For major/feature releases, I will email a broader
    list (no more than once every 3-6 months):
      pangeo@googlegroups.com, xarray@googlegroups.com,
      pyaos@lists.johnny-lin.com
    Google search will turn up examples of prior release announcements (look for
    "ANN aospy").

Note on version numbering:

We follow a rough approximation of semantic version. Only major releases (0.X.0)
show include breaking changes. Minor releases (0.X.Y) are for bug fixes and
backwards compatible new features, but if a sufficient number of new features
have arrived we will issue a major release even if there are no compatibility
breaks.

Once the project reaches a sufficient level of maturity for a 1.0.0 release, we
intend to follow semantic versioning more strictly.