From e7debe60495d43a813e56db60ce375774cd9dbe8 Mon Sep 17 00:00:00 2001
From: Sumana Harihareswara <sh@changeset.nyc>
Date: Fri, 2 Mar 2018 09:48:42 -0500
Subject: [PATCH] Add maintainer and release checklists to docs

---
 docs/contributing.rst | 75 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 669e9966..a2f61695 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -110,6 +110,81 @@ uploaded to (which the user can specify either as a default, in the
 :file:`.pypirc` file, or pass on the command line), and the methods
 that upload the package securely to a URL.
 
+Adding a maintainer
+-------------------
+
+A checklist for adding a new maintainer to the project.
+
+#. Add her as a Member in the GitHub repo settings. (This will also
+   give her privileges on the `Travis CI project
+   <https://travis-ci.org/pypa/twine>`_.)
+#. Get her Test PyPI and canon PyPI usernames and add her as a
+   Maintainer on `our Test PyPI project
+   <https://test.pypi.org/manage/project/twine/collaboration/>`_ and
+   `canon PyPI
+   <https://pypi.org/manage/project/twine/collaboration/>`_.
+
+
+Making a new release
+--------------------
+
+A checklist for creating, testing, and distributing a new version.
+
+#. Choose a version number, e.g., "1.10."
+
+#. Merge the last planned PR before the new release:
+
+   #. Add new changes to :file:`docs/changelog.rst`.
+   #. Update the ``__version__`` string in :file:`twine/__init__.py`,
+      which is where :file:`setup.py` pulls it from, with `{number}rc1`
+      for "release candidate 1".
+   #. Update copyright dates.
+
+#. Run tests:
+
+   #. ``tox -e py{27,34,25,36}``
+   #. ``tox -e pep8``
+   #. ``tox -e docs`` (this checks the Sphinx docs and uses
+      ``readme_renderer`` to check that the ``long_description`` and other
+      metadata will render fine on the PyPI description)
+
+#. Create a git tag with ``git tag -sam 'Release v{number}' {number}``.
+
+   * ``{number}``, such as ``1.10.1rc1``
+   * ``-s`` signs it with your PGP key
+   * ``-a`` creates an annotated tag for GitHub
+   * ``-m`` adds the message; optional if you want to compose a longer
+     message
+
+#. View your tag: ``git tag -v {number}``
+#. Push your tag: ``git push upstream {number}``.
+#. Delete old distributions: ``rm dist/*``.
+#. Create distributions with ``python setup.py sdist bdist_wheel``.
+#. Set your TestPyPI and canon PyPI credentials in your session with
+   ``keyring`` (docs forthcoming).
+#. Upload to Test PyPI: :command:`twine upload --repository-url
+   https://test.pypi.org/legacy/ --skip-existing dist/*`
+#. Verify that everything looks good, downloads ok, etc. Make needed fixes.
+#. Merge the last PR before the new release:
+
+   #. Add new changes and new release to :file:`docs/changelog.rst`,
+      with the new version `{number}`, this time without the ``rc1`` suffix.
+   #. Update the ``__version__`` string in :file:`twine/__init__.py`
+      with `{number}`.
+
+#. Run tests again. Check the changelog to verify that it looks right.
+#. Create a new git tag with ``git tag -sam 'Release v{number}' {number}``.
+#. View your tag: ``git tag -v {number}``
+#. Push your tag: ``git push upstream {number}``.
+#. Delete old distributions: ``rm dist/*``.
+#. Create distributions with ``python setup.py sdist bdist_wheel``.
+#. On a Monday or Tuesday, upload to canon PyPI: :command:`twine
+   upload --skip-existing dist/*`
+
+   .. note:: Will be replaced by ``tox -e release`` at some point.
+#. Send announcement email to `pypa-dev mailing list`_ and celebrate.
+
+
 Future development
 ------------------