Update release and contributing docs. [skip ci]

CONTRIBUTING.rst

@@ -23,11 +23,10 @@ There are a number of systems in place to help ensure gevent is of the
 highest possible quality:
 
 - A test suite is run for every push and pull request submitted. Travis
-  CI is used to test on Linux, and `AppVeyor`_ runs the builds on
+  CI is used to test on Linux and macOS, and `AppVeyor`_ runs the builds on
   Windows. Pull requests with tests that don't pass will be
   automatically failed.
 
-
   .. image:: https://travis-ci.org/gevent/gevent.svg?branch=master
      :target: https://travis-ci.org/gevent/gevent
 

docs/development/getting_started.rst

@@ -56,3 +56,62 @@ can be done in one line by installing the ``dev-requirements.txt`` file::
    This pip command does not work with pip 19.1. Either use pip 19.0
    or below, or use pip 19.1.1 with ``--no-use-pep517``. See `issue
    1412 <https://github.com/gevent/gevent/issues/1412>`_.
+
+Making Changes
+==============
+
+When adding new features (functions, methods, modules), be sure to
+provide docstrings. The docstring should end with Sphinx's
+`versionadded directive
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded>`_,
+using a version string of "NEXT". This string will automatically be
+replaced with the correct version during the release process.
+
+For example:
+
+.. code-block:: python
+
+   def make_plumbus(schleem, rub_fleeb=True):
+      """
+      Produces a plumbus.
+
+      :param int scheem: The number of schleem to use.
+          Possibly repurposed.
+      :keyword bool rub_fleeb: Whether to rub the fleeb.
+          Rubbing the fleeb is important, so only disable
+          if you know what you're doing.
+      .. versionadded:: NEXT
+      """
+
+When making a change to an existing feature that has already been
+released, apply the appropriate `versionchanged
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged>`_
+or `deprecated
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated>`_
+directive, also using "NEXT".
+
+.. code-block:: python
+
+   def make_plumbus(schleem, rub_fleeb=True):
+      """
+      Produces a plumbus.
+
+      :param int schleem: The schleem to use.
+          Possibly repurposed.
+      :keyword bool rub_fleeb: Whether to rub the fleeb.
+          Rubbing the fleeb is important, so only disable
+          if you know what you're doing.
+      :return: A :class:`Plumbus`.
+      .. versionadded:: 20.04.0
+      .. versionchanged:: NEXT
+         The *rub_fleeb* parameter is ignored; the fleeb
+         must always be rubbed.
+      """
+
+    def extract_fleeb_juice():
+        """
+        Get the fleeb juice.
+
+        .. deprecated:: NEXT
+           Extracting fleeb juice now happens automatically.
+        """

docs/development/release_process.rst

@@ -2,10 +2,18 @@
  Release Process
 =================
 
-Release Cadence
-===============
+Release Cadence and Versions
+============================
 
-TODO: Write me.
+After :doc:`gevent 1.5 <../whatsnew_1_5>`, gevent releases switched to
+`CalVer <https://calver.org>`_, using the scheme ``YY.0M.Micro``
+(two-digit year, zero-padded month, micro/patch number). Thus the
+first release in April of 2020 would be version ``20.04.0``. A second
+release would be ``20.04.1``, etc. The first release in May
+would be ``20.05.0``, and so on.
+
+If there have been changes to master, gevent should produce a release
+at least once a month.
 
 Deprecation Policy
 ==================
@@ -39,26 +47,16 @@ Releasing gevent
           maintainers.
 
 gevent is released using `zest.releaser
-<https://pypi.org/project/zest.releaser/>`_. The general flow is
-something like this:
+<https://pypi.org/project/zest.releaser/>`_. Binary wheels are
+published automatically by Travis CI (macOS and manylinux) and
+Appveyor (Windows) when a tag is uploaded.
+
 
 1. Push all relevant changes to master.
-2. From the gevent working copy, run ``prerelease``. Fix any issues it
+2. From the gevent working copy, run ``fullrelease``. Fix any issues it
    brings up. Let it bump the version number (or enter the correct
-   one) and commit.
-3. Run ``release``. Let it create the tag and commit it; let it create
-   an sdist, but **do not** let it upload it.
-4. Push the tag and master to github.
-5. Let appveyor build the tag. Download all the built wheels from that
-   release. The easiest way to do that is with Ned Batchelder's
-   `appveyor-download.py script
-   <https://bitbucket.org/ned/coveragepy/src/tip/ci/download_appveyor.py>`_.
-6. Meanwhile, spin up docker and from the root of the gevent checkout
-   run ``scripts/releases/make-manylinux``. This creates wheels in
-   ``wheelhouse/``.
-7. If on a mac, ``cd scripts/releases && ./geventreleases.sh``. This
-   creates wheels in ``/tmp/gevent/``.
-8. Upload the Appveyor, manylinux, and mac wheels to pypi using
-   ``twine``. Also be sure to upload the sdist!
-9. Run ``postrelease``, let it bump the version and push the changes
-   to github.
+   one), commit, create the tag, create the sdist, upload the sdist
+   and push the tag to GitHub.
+3. Monitor the build process on the CI systems. If particular builds
+   fail due to test instability, re-run them to allow the binary wheel
+   to be uploaded.

scripts/releases/geventreleases.sh

@@ -8,18 +8,20 @@ mkdir /tmp/gevent/
 
 
 # 2.7 is a python.org build, builds a 10_6_intel wheel
-./geventrel.sh /usr/local/bin/python2.7
+./geventrel.sh /usr/local/bin/python2.7 &
 
 # 3.5 is a python.org build, builds a 10_6_intel wheel
-./geventrel.sh /usr/local/bin/python3.5
+./geventrel.sh /usr/local/bin/python3.5 &
 
 # 3.6 is a python.org build, builds a 10_6_intel wheel
-./geventrel.sh /usr/local/bin/python3.6
+./geventrel.sh /usr/local/bin/python3.6 &
 
 # 3.7 is a python.org build, builds a 10_6_intel wheel
-./geventrel.sh /usr/local/bin/python3.7
-./geventrel.sh /usr/local/bin/python3.8
+./geventrel.sh /usr/local/bin/python3.7 &
+./geventrel.sh /usr/local/bin/python3.8 &
 
 
 # PyPy 4.0
-./geventrel.sh `which pypy`
+./geventrel.sh `which pypy` &
+
+wait