===============
Release Process
===============

In order to allow for rapid, predictable releases, Setuptools uses a
mechanical technique for releases, enacted by Travis following a
successful build of a tagged release per
`PyPI deployment <https://docs.travis-ci.com/user/deployment/pypi>`_.

To cut a release, install and run ``bumpversion {part}`` where ``part``
is major, minor, or patch based on the scope of the changes in the
release. Then, push the commits to the master branch. If tests pass,
the release will be uploaded to PyPI.

Bootstrap Bookmark
------------------

Setuptools has a bootstrap script (ez_setup.py) which is hosted in the
repository and must be updated with each release (to bump the default version).
The "published" version of the script is the one indicated by the ``bootstrap``
branch.

Therefore, the latest bootstrap script can be retrieved by checking out the
repository at that bookmark. It's also possible to get the bootstrap script for
any particular release by grabbing the script from that tagged release.

The officially-published location of the bootstrap script is hosted on Python
infrastructure (#python-infra on freenode) at https://bootstrap.pypa.io and
is updated every fifteen minutes from the bootstrap script. Sometimes,
especially when the bootstrap script is rolled back, this
process doesn't work as expected and requires manual intervention.

Release Frequency
-----------------

Some have asked why Setuptools is released so frequently. Because Setuptools
uses a mechanical release process, it's very easy to make releases whenever the
code is stable (tests are passing). As a result, the philosophy is to release
early and often.

While some find the frequent releases somewhat surprising, they only empower
the user. Although releases are made frequently, users can choose the frequency
at which they use those releases. If instead Setuptools contributions were only
released in batches, the user would be constrained to only use Setuptools when
those official releases were made. With frequent releases, the user can govern
exactly how often he wishes to update.

Frequent releases also then obviate the need for dev or beta releases in most
cases. Because releases are made early and often, bugs are discovered and
corrected quickly, in many cases before other users have yet to encounter them.

Release Managers
----------------

Additionally, anyone with push access to the master branch has access to cut
releases.
