New maintainer release checklist

docs/changelog.rst

@@ -4,6 +4,7 @@
 Changelog
 =========
 
+* :support:`314` Add new maintainer, release checklists.
 * :bug:`322 major` Raise exception if attempting upload to deprecated legacy
   PyPI URLs.
 * :feature:`320` Remove PyPI as default ``register`` package index.

docs/contributing.rst

@@ -91,18 +91,141 @@ Architectural overview
 ----------------------
 
 Twine is a command-line tool for interacting with PyPI securely over
-HTTPS. Its command line arguments are parsed in
-:file:`twine/cli.py`. Currently, twine has two principal functions:
-uploading new packages and registering new `projects`_. The code for
-registering new projects is in :file:`twine/commands/register.py`, and
-the code for uploading is in :file:`twine/commands/upload.py`. The
-file :file:`twine/package.py` contains a single class,
-``PackageFile``, which hashes the project files and extracts their
-metadata. The file :file:`twine/repository.py` contains the
-``Repository`` class, whose methods control the URL the package is
-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.
+HTTPS. Its three purposes are to be:
+
+1. A user-facing tool for publishing on pypi.org
+2. A user-facing tool for publishing on other Python package indexes
+   (e.g., ``devpi`` instances)
+3. A useful API for other programs (e.g., ``zest.releaser``) to call
+   for publishing on any Python package index
+
+
+Currently, twine has two principal functions: uploading new packages
+and registering new `projects`_ (``register`` is no longer supported
+on PyPI, and is in Twine for use with other package indexes).
+
+Its command line arguments are parsed in :file:`twine/cli.py`. The
+code for registering new projects is in
+:file:`twine/commands/register.py`, and the code for uploading is in
+:file:`twine/commands/upload.py`. The file :file:`twine/package.py`
+contains a single class, ``PackageFile``, which hashes the project
+files and extracts their metadata. The file
+:file:`twine/repository.py` contains the ``Repository`` class, whose
+methods control the URL the package is 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.
+
+Where Twine gets configuration and credentials
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A user can set the repository URL, username, and/or password via
+command line, ``.pypirc`` files, environment variables, and
+``keyring``.
+
+
+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.15."
+
+#. 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 Twine tests:
+
+   #. ``tox -e py{27,34,35,36,py}``
+   #. ``tox -e pep8`` for the linter
+   #. ``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)
+
+#. Run integration tests with downstreams:
+
+   #. Test ``pypiserver`` support:
+
+      .. code-block:: console
+
+         git clone [email protected]:pypiserver/pypiserver
+         cd pypiserver
+         tox -e pre_twine
+
+   #. Create a test package to upload to Test PyPI, version-control it
+      with git, and test ``zest.releaser`` per directions in `this
+      comment
+      <https://github.com/pypa/twine/pull/314#issuecomment-370525038>`_.
+   #. Test ``devpi`` support:
+
+      .. code-block:: console
+
+        pip install devpi-client
+        devpi use https://m.devpi.net
+        devpi user -c {username} password={password}
+        devpi login {username} --password={password}
+        devpi index -c testpypi type=mirror mirror_url=https://test.pypi.org/simple/
+        devpi use {username}/testpypi
+        python setup.py sdist
+        twine upload --repository-url https://m.devpi.net/{username}/testpypi/ dist/{testpackage}.tar.gz
+
+#. Create a git tag with ``git tag -sam 'Release v{number}' {number}``.
+
+   * ``{number}``, such as ``1.15.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
 ------------------

docs/requirements.txt

@@ -1,6 +1,7 @@
 doc8>=0.8.0
+readme-renderer>=17.4
 releases>=1.4.0
 Sphinx>=1.7.0
 sphinx_rtd_theme>=0.2.4
 tox>=2.9.1
-twine>=1.9.1
+twine>=1.10.0

tox.ini

@@ -18,6 +18,7 @@ commands =
     sphinx-build -W -b doctest -d {envtmpdir}/doctrees docs docs/_build/html
     doc8 docs
     sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees docs docs/_build/linkcheck
+    python setup.py check -r -s
 
 [testenv:release]
 deps =