Distributing a new release
==========================

- For clarity, we define releases as follows.

  - Alpha, beta, dev and similar statuses do not qualify whether a release is
    major or minor. The term "pre-release" means alpha, beta, or dev.

  - A release is final when it is no longer pre-release.

  - A *major* release is where the first number either before or after the
    first dot increases. Examples: 0.9.0 to 2.0.

  - A *minor* or *bug fix* release is where the number after the second dot
    increases. Example: 2.0 to 2.0.1.

Prepare new release branch
--------------------------

- Create a new release branch, incrementing the version number.

- Do any necessary branch merges (e.g., master to branch, branch to master).

- On release branch:

  $ git pull

- Do platform test via tox:

- Make sure your Python has ``setuptools-git``, ``twine``, and ``wheel``
  installed:

    $ $VENV/bin/easy_install setuptools-git twine wheel

- Do a platform test:

    $ tox -r

- Ensure all features of the release are documented (audit CHANGES.txt or
  communicate with contributors).

- Change CHANGES.txt heading to reflect the new version number.

- Update README.rst to use correct versions of badges and URLs according to
  each branch and context, i.e., RTD "latest" == GitHub/Travis "2.0-branch".

- Update whatsnew-X.X.rst in docs to point at change log entries for
  individual releases if applicable.

- For major version releases, in contributing.md, update branch descriptions.

- For major version releases, in docs/conf.py, update values under
  html_theme_options for in_progress and outdated across master, releasing
  branch, and previously released branch. Also in the previously released
  branch only, uncomment the sections to enable pylons_sphinx_latesturl.

- Change setup.py version to the release version number.

- Make sure PyPI long description renders (requires ``collective.dist``
  installed into your Python)::

    $ $VENV/bin/python setup.py check -r

- Build an sdist and a wheel:

    $ $VENV/bin/python setup.py sdist bdist_wheel

- Release the wheels to PyPI:

    $ $VENV/bin/twine upload dist/deform-X.Y*

- Upload a git tag for the release:

    $ git tag X.Y
    $ git push origin X.Y

- Update RTD to render a new version of the docs at that tag X.Y and set X.Y
  as the default branch such that /latest/ points to it.

- Publish new version of docs.

- Update deform demo site

- Announce to Twitter.

```
Deform 2.x released.

PyPI
https://pypi.python.org/pypi/deform/2.x

=== One time only for new version, first pre-release ===
What's New
http://docs.pylonsproject.org/projects/deform/en/2.x-branch/whatsnew-2.X.html
=== For all subsequent pre-releases ===
Changes
http://docs.pylonsproject.org/projects/deform/en/2.X-branch/changes.html#version-yyyy-mm-dd

Issues
https://github.com/Pylons/deform/issues
```

- Announce to maillist.

```
Deform 2.X.X has been released.

Here are the changes:

<<changes>>

Links

- Widget demos http://deformdemo.repoze.org/

- Documentation http://docs.pylonsproject.org/projects/deform/en/master/

- Github https://github.com/pylons/deform

- PyPi https://pypi.python.org/pypi/deform/

Enjoy, and please report any issues you find to the issue tracker at
https://github.com/Pylons/deform/issues

Thanks!

- Deform developers
```
