From 281fcd5a58f6c16d5d27dd52954f3bcb8736bb33 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 30 May 2017 21:26:41 -0300
Subject: [PATCH] Update HOWTORELEASE

* Remove the CHANGELOG step now that it is automated;
* Overall clean-up and formatting, trying to make the steps more
  explicit;
---
 HOWTORELEASE.rst | 46 +++++++++++++++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 17 deletions(-)

diff --git a/HOWTORELEASE.rst b/HOWTORELEASE.rst
index 6c0ec5a62..f094e369a 100644
--- a/HOWTORELEASE.rst
+++ b/HOWTORELEASE.rst
@@ -3,47 +3,59 @@ How to release pytest
 
 .. important::
 
-    pytest releases must be prepared on **linux** because the docs and examples expect
+    pytest releases must be prepared on **Linux** because the docs and examples expect
     to be executed in that platform.
 
 #. Install development dependencies in a virtual environment with::
 
     pip3 install -r tasks/requirements.txt
 
-#. Create a branch ``release-X.Y.Z`` with the version for the release. Make sure it is up to date
-   with the latest ``master`` (for patch releases) and with the latest ``features`` merged with
-   the latest ``master`` (for minor releases). Ensure your are in a clean work tree.
+#. Create a branch ``release-X.Y.Z`` with the version for the release.
 
-#. Check and finalize ``CHANGELOG.rst`` (will be automated soon).
+   * **patch releases**: from the latest ``master``;
 
-#. Execute to automatically generate docs, announcements and upload a package to
+   * **minor releases**: from the latest ``features``; then merge with the latest ``master``;
+
+   Ensure your are in a clean work tree.
+
+#. Generate docs, changelog, announcements and upload a package to
    your ``devpi`` staging server::
 
      invoke generate.pre_release <VERSION> <DEVPI USER> --password <DEVPI PASSWORD>
 
-   If ``--password`` is not given, it is assumed the user is already logged in. If you don't have
-   an account, please ask for one!
+   If ``--password`` is not given, it is assumed the user is already logged in ``devpi``.
+   If you don't have an account, please ask for one.
 
-#. Run from multiple machines::
+#. Open a PR for this branch targeting ``master``.
 
-     devpi use https://devpi.net/USER/dev
-     devpi test pytest==VERSION
+#. Test the package
 
-   Alternatively, you can use `devpi-cloud-tester <https://github.com/nicoddemus/devpi-cloud-tester>`_ to test
-   the package on AppVeyor and Travis (follow instructions on the ``README``).
+   * **Manual method**
 
-#. Check that tests pass for relevant combinations with::
+     Run from multiple machines::
+
+       devpi use https://devpi.net/USER/dev
+       devpi test pytest==VERSION
+
+     Check that tests pass for relevant combinations with::
 
        devpi list pytest
 
-   or look at failures with "devpi list -f pytest".
+   * **CI servers**
 
-#. Feeling confident? Publish to PyPI::
+     Configure a repository as per-instructions on
+     devpi-cloud-test_ to test the package on Travis_ and AppVeyor_.
+     All test environments should pass.
+
+#. Publish to PyPI::
 
       invoke generate.publish_release <VERSION> <DEVPI USER> <PYPI_NAME>
 
    where PYPI_NAME is the name of pypi.python.org as configured in your ``~/.pypirc``
    file `for devpi <http://doc.devpi.net/latest/quickstart-releaseprocess.html?highlight=pypirc#devpi-push-releasing-to-an-external-index>`_.
 
-
 #. After a minor/major release, merge ``features`` into ``master`` and push (or open a PR).
+
+.. _devpi-cloud-test: https://github.com/obestwalter/devpi-cloud-test
+.. _AppVeyor: https://www.appveyor.com/
+.. _Travis: https://travis-ci.org