Update release notes; add towncrier configuration. [skip ci]

dev-requirements.txt

@@ -7,8 +7,11 @@ pylint>=1.8.0 ; python_version < "3.4"
 # pylint 2 needs astroid 2; unfortunately, it uses `typed_ast`
 # which has a C extension that doesn't build on PyPy
 pylint >= 2.3.1 ; python_version >= "3.4"  and platform_python_implementation == "CPython"
-astroid >= 2.2.5 ; python_version >= "3.4" and platform_python_implementation == "CPython"
+astroid >= 2.2.5 ; python_version >= "3.4" and
+platform_python_implementation == "CPython"
 
+# For generating CHANGES.rst
+towncrier; python_version >= 3.5
 
 # benchmarks use this
 pyperf >= 1.6.1

docs/_templates/hr-between-versions.rst.tmpl

+{{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 3)}}
+
+{% for section, _ in sections.items() %}
+{% set underline = underlines[0] %}{% if section %}{{section}}
+{{ underline * section|length }}{% set underline = underlines[1] %}
+
+{% endif %}
+
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section]%}
+{{ definitions[category]['name'] }}
+{{ underline * definitions[category]['name']|length }}
+
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category].items() %}
+- {{ text }}
+  {{ values|join(',\n  ') }}
+{% endfor %}
+
+{% else %}
+- {{ sections[section][category]['']|join(', ') }}
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+
+{% else %}
+{% endif %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}
+{% endfor %}
+----

docs/changelog_1_4.rst

+===========
+ Changelog
+===========
+
+.. currentmodule:: gevent
+
+
+1.4.0 (2019-01-04)
+==================
+
+- Build with Cython 0.29 in '3str' mode.
+
+- Test with PyPy 6.0 on Windows.
+
+- Add support for application-wide callbacks when ``Greenlet`` objects
+  are started. See :pr:`1289`, provided by Yury Selivanov.
+
+- Fix consuming a single ready object using
+  ``next(gevent.iwait(objs))``. Previously such a construction would
+  hang because `iter` was not called. See :pr:`1288`, provided by Josh
+  Snyder. This is not recommended, though, as unwaited objects will
+  have dangling links (but see next item).
+
+- Make `gevent.iwait` return an iterator that can now also be used as
+  a context manager. If you'll only be consuming part of the iterator,
+  use it in a ``with`` block to avoid leaking resources. See
+  :pr:`1290`, provided by Josh Snyder.
+
+- Fix semaphores to immediately notify links if they are ready and
+  ``rawlink()`` is called. This behaves like ``Event`` and
+  ``AsyncEvent``. Note that the order in which semaphore links are
+  called is not specified. See :issue:`1287`, reported by Dan Milon.
+
+- Improve safety of handling exceptions during interpreter shutdown.
+  See :issue:`1295` reported by BobDenar1212.
+
+- Remove the deprecated ability to specify ``GEVENT_RESOLVER`` and
+  other importable settings as a ``path/to/a/package.module.item``.
+  This had race conditions and didn't work with complicated resolver
+  implementations. Place the required package or module on `sys.path`
+  first.
+
+- Reduce the chances that using the blocking monitor functionality
+  could result in apparently random ``SystemError:
+  Objects/tupleobject.c: bad argument to internal function``. Reported
+  in :issue:`1302` by Ulrich Petri.
+
+- Refactored the gevent test runner and test suite to make them more
+  reusable. In particular, the tests are now run with ``python -m
+  gevent.tests``. See :issue:`1293`.
+
+- Make a monkey-patched ``socket.getaddrinfo`` return socket module
+  enums instead of plain integers for the socket type and address
+  family on Python 3. See :issue:`1310` reported by TheYOSH.
+
+  .. note:: This requires Python 3.4.3 or above due to an undocumented
+            change in that version.
+
+- Make gevent's pywsgi server set the non-standard environment value
+  ``wsgi.input_terminated`` to True. See :issue:`1308`.
+
+- Make `gevent.util.assert_switches` produce more informative messages
+  when the assertion fails.
+
+- Python 2: If a `gevent.socket` was closed asynchronously (in a
+  different greenlet or a hub callback), `AttributeError` could result
+  if the socket was already in use. Now the correct socket.error
+  should be raised.
+
+- Fix :meth:`gevent.threadpool.ThreadPool.join` raising a
+  `UserWarning` when using the libuv backend. Reported in
+  :issue:`1321` by ZeroNet.
+
+- Fix ``FileObjectPosix.seek`` raising `OSError` when it should have
+  been `IOError` on Python 2. Reported by, and PR by, Ricardo Kirkner.
+  See :issue:`1323`.
+
+- Upgrade libuv from 1.23.2 to 1.24.0.

docs/changes/.gitignore

+!.gitignore

docs/contents.rst

@@ -38,8 +38,9 @@ Developing and Packaging gevent
 .. toctree::
    :maxdepth: 2
 
-   installing_from_source
-   development
+   development/installing_from_source
+   development/index
+   development/release_process
 
 
 Related Information

docs/development/release_process.rst

+=================
+ Release Process
+=================
+
+Release Cadence
+===============
+
+TODO: Write me.
+
+Deprecation Policy
+==================
+
+.. This is largely based on what pip says.
+
+Any change to gevent that removes or significantly alters user-visible
+behavior that is described in the gevent documentation will be
+deprecated for a minimum of 6 months before the change occurs.
+Deprecation will be called out in the documentation and in some cases
+with a runtime warning when the feature is used (because of the
+performance sensitive nature of gevent, not all deprecations will have
+a runtime warning). Longer deprecation periods, or deprecation
+warnings for behavior changes that would not normally be covered by
+this policy, are also possible depending on circumstances, but this is
+at the discretion of the gevent developers.
+
+Note that the documentation is the sole reference for what counts as
+agreed behavior. If something isn’t explicitly mentioned in the
+documentation, it can be changed without warning, or any deprecation
+period, in a gevent release. However, we are aware that the documentation
+isn’t always complete - PRs that document existing behavior with the
+intention of covering that behavior with the above deprecation process
+are always acceptable, and will be considered on their merits.

docs/install.rst

@@ -11,8 +11,8 @@
 Supported Platforms
 ===================
 
-`gevent 1.5`_ runs on Python 2.7.9 and up, and Python 3.5, 3.6 and
-3.7. gevent requires the `greenlet <https://greenlet.readthedocs.io>`_
+`gevent 1.5`_ runs on Python 2.7.9 and up, and Python 3.5, 3.6, 3.7 and
+3.8. gevent requires the `greenlet <https://greenlet.readthedocs.io>`_
 library and will install the `cffi`_ library by default on Windows.
 The cffi library will become the default on all platforms in a future
 release of gevent.
@@ -65,9 +65,8 @@ Installation
 .. note::
 
    This section is about installing released versions of gevent as
-   distributed on the `Python Package Index`_. For developing with
-   gevent, including running tests, see `development`_. For building
-   gevent from source, including customizing the build and embedded
+   distributed on the `Python Package Index`_. For building gevent
+   from source, including customizing the build and embedded
    libraries, see `Installing From Source`_.
 
 .. _Python Package Index: http://pypi.org/project/gevent
@@ -132,18 +131,10 @@ test
     Everything needed to run the complete gevent test suite.
 
 
-Development
-===========
-
-For development information, including installing from git and running
-tests, see `development`_.
-
-
 .. _`pip`: https://pip.pypa.io/en/stable/installing/
 .. _`wheels`: http://pythonwheels.com
 .. _`gevent 1.5`: whatsnew_1_5.html
-.. _`development`: development.html
-.. _`Installing From Source`: installing_from_source.html
+.. _`Installing From Source`: http://gevent.org/development/installing_from_source.html
 
 .. _`cffi`: https://cffi.readthedocs.io
 .. _`limitations in libev`: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#WIN32_PLATFORM_LIMITATIONS_AND_WORKA

docs/whatsnew_1_3.rst

@@ -7,7 +7,7 @@
 .. toctree::
    :maxdepth: 2
 
-   changelog
+   changelog_1_3
 
 Detailed information on what has changed is available in the
 :doc:`changelog`. This document summarizes the most important changes

docs/whatsnew_1_4.rst

@@ -7,7 +7,7 @@
 .. toctree::
    :maxdepth: 2
 
-   changelog
+   changelog_1_4
 
 Detailed information on what has changed is available in the
 :doc:`changelog`. This document summarizes the most important changes

docs/whatsnew_1_5.rst

@@ -7,40 +7,57 @@
 .. toctree::
    :maxdepth: 2
 
-   changelog
-
-.. caution::
-
-   This document is currently being written.
+   changelog_1_5
 
 Detailed information on what has changed is available in the
 :doc:`changelog`. This document summarizes the most important changes
 since :doc:`gevent 1.4 <whatsnew_1_4>`.
 
-gevent 1.5 is a small maintenance release featuring bug fixes and a
-small number of API improvements.
+gevent 1.5 is a maintenance and feature release including bug fixes and a
+number of API improvements.
+
+Versioning
+==========
+
+Future releases of gevent will use a scheme similar to `CalVer
+<https://calver.org>`_. See :doc:`development/release_process` for information
+on future deprecations and feature removals.
 
 Platform Support
 ================
 
 gevent 1.5 drops support for Python 3.4, and drops support for PyPy
-< 7.
+< 7. It also adds official support for Python 3.8.
+
+gevent is tested with CPython 2.7.17, 3.5.9, 3.6.10, 3.7.7, 3.8.2,
+PyPy 2 7.3.0 and PyPy3 7.3.0.
 
 Packaging Changes
 =================
 
 gevent now distributes `manylinux2010
 <https://www.python.org/dev/peps/pep-0571/>`_ binary wheels for Linux,
-instead of the older ``manylinux1`` standard. This updated
-platform tag allows gevent to distribute libuv support by default.
-CentOS 6 is the baseline for this tag.
+instead of the older ``manylinux1`` standard. This updated platform
+tag allows gevent to distribute libuv support by default. CentOS 6 is
+the baseline for this tag.
+
+.. note:: Older releases, such as RHEL 5, are no longer supported.
+
+gevent bundles a ``pyproject.toml`` now. This is useful for building
+from source.
+
+The legacy ``Makefile`` has been removed in favor of built-in setup.py
+commands.
+
+Certain environment variables used at build time have been deprecated
+and renamed.
 
 Library Updates
 ===============
 
-The bundled version of libuv has been updated from 1.24 to 1.27, libev
-has been updated from 4.23 to 4.25, and c-ares has been updated from
-1.24 to 1.15.
+The bundled version of libuv has been updated from 1.24 to 1.34, libev
+has been updated from 4.23 to 4.31, and c-ares has been updated from
+1.14 to 1.15.
 
 Version 1.16 or newer of dnspython is required to use the dnspython resolver.
 
@@ -55,3 +72,13 @@ tests that require Internet access, one could disable the ``network``
 resource using ``python -m gevent.tests -u-network`` or
 ``GEVENTTEST_USE_RESOURCES=-network python -m gevent.tests``. See
 :ref:`limiting-test-resource-usage` for more information.
+
+Other Changes
+=============
+
+The file objects have been reworked to support more modes and behave
+more like the builtin :func:`open` or func:`io.open` functions and
+:mod:`io` classes. Previously they essentially only worked with binary
+streams. Certain default values have been changed as well.
+
+The deprecated magic proxy object ``gevent.signal`` has been removed.

pyproject.toml

@@ -20,3 +20,12 @@ requires = [
      # Python 3.7 requires at least 0.4.14, which is ABI incompatible with earlier
      "greenlet>=0.4.14 ; platform_python_implementation == 'CPython'",
 ]
+
+[tool.towncrier]
+directory = "docs/changes"
+filename = "CHANGES.rst"
+package = "gevent"
+package_dir = "src"
+issue_format = ":issue:`{issue}`"
+title_format = false
+template = "docs/_templates/hr-between-versions.rst.tmpl"