Start next-release notes

diff --git a/docs/releases.rst b/docs/releases.rst
index 31d3fe39e6ad704173951b8331275516c75bf566..661d398ade0cce613d6ea3865e18f80275609dcf 100644 (file)
--- a/docs/releases.rst
+++ b/docs/releases.rst
@@ -4,6 +4,7 @@ Release notes
 .. toctree::
    :maxdepth: 2
 
+   releases/next
    releases/v4.1.0
    releases/v4.0.2
    releases/v4.0.1

diff --git a/docs/releases/next.rst b/docs/releases/next.rst
new file mode 100644 (file)
index 0000000..8cf004d
--- /dev/null
+++ b/docs/releases/next.rst
@@ -0,0 +1,63 @@
+What's new in the next version of Tornado
+=========================================
+
+In Progress
+-----------
+
+Backwards-compatibility notes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* ``SSLIOStream.connect`` and `.IOStream.start_tls` now validate certificates
+  by default.
+* Certificate validation will now use the system CA root certificates instead
+  of ``certifi`` when possible (i.e. Python 2.7.9+ or 3.4+). This includes
+  `.IOStream` and ``simple_httpclient``, but not ``curl_httpclient``.
+* The default SSL configuration has become stricter, using
+  `ssl.create_default_context` where available.
+
+
+`tornado.gen`
+~~~~~~~~~~~~~
+
+* On Python 3, catching an exception in a coroutine no longer leads to
+  leaks via ``Exception.__context__``.
+
+`tornado.ioloop`
+~~~~~~~~~~~~~~~~
+
+* `.PeriodicCallback` is now more efficient when the clock jumps forward
+  by a large amount.
+
+`tornado.iostream`
+~~~~~~~~~~~~~~~~~~
+
+* ``SSLIOStream.connect`` and `.IOStream.start_tls` now validate certificates
+  by default.
+
+`tornado.log`
+~~~~~~~~~~~~~
+
+* `.define_logging_options` now works correctly when given a non-default
+  ``options`` object.
+
+``tornado.simple_httpclient``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Improved performance on Python 3 by reusing a single `ssl.SSLContext`.
+
+`tornado.util`
+~~~~~~~~~~~~~~
+
+* `.import_object` now supports unicode strings on Python 2.
+
+`tornado.web`
+~~~~~~~~~~~~~
+
+* Passing ``secure=False`` or ``httponly=False`` to
+  `.RequestHandler.set_cookie` now works as expected (previously only the
+  presence of the argument was considered and its value was ignored).
+
+`tornado.websocket`
+~~~~~~~~~~~~~~~~~~~
+
+* The ``on_close`` method will no longer be called more than once.

diff --git a/tornado/log.py b/tornado/log.py
index e4cc91f2106e8caf780d40207dc620c6c5d9adcf..c68dec46bad5f1331fb121d6f3c0d43047e50484 100644 (file)
--- a/tornado/log.py
+++ b/tornado/log.py
@@ -206,6 +206,14 @@ def enable_pretty_logging(options=None, logger=None):
 
 
 def define_logging_options(options=None):
+    """Add logging-related flags to ``options``.
+
+    These options are present automatically on the default options instance;
+    this method is only necessary if you have created your own `.OptionParser`.
+
+    .. versionadded:: 4.2
+        This function existed in prior versions but was broken and undocumented until 4.2.
+    """
     if options is None:
         # late import to prevent cycle
         from tornado.options import options