Add Whats New in WebOb 1.8 document

2 files changed, 100 insertions, 0 deletions

diff --git a/docs/index.txt b/docs/index.txt
index f96da68..805c5bb 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -40,6 +40,8 @@ Reference material for every public API exposed by WebOb:
    api/*
 
 
+.. _experimental-api:
+
 Experimental API
 ================
 
@@ -307,6 +309,7 @@ Change History
    whatsnew-1.5
    whatsnew-1.6
    whatsnew-1.7
+   whatsnew-1.8
    changes
 
 Status and License
diff --git a/docs/whatsnew-1.8.txt b/docs/whatsnew-1.8.txt
new file mode 100644
index 0000000..d102d83
--- /dev/null
+++ b/docs/whatsnew-1.8.txt
@@ -0,0 +1,97 @@
+What's New in WebOb 1.8
+=======================
+
+Compatibility
+~~~~~~~~~~~~~
+
+- WebOb is no longer officially supported on Python 3.3 which was EOL'ed on
+  2017-09-29.
+
+  Please pin to `WebOb~=1.7` which was tested against Python 3.3, and upgrade
+  your Python version.
+
+Backwards Incompatibilities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Many changes have been made to the way WebOb does Accept handling, not just
+  for the ``Accept`` header itself, but also for ``Accept-Charset``,
+  ``Accept-Encoding`` and ``Accept-Language``. This was a `Google Summer of
+  Code <https://developers.google.com/open-source/gsoc/>`_ project completed by
+  Whiteroses (https://github.com/whiteroses). Many thanks to Google for running
+  GSoC, the Python Software Foundation for organising and a huge thanks to Ira
+  for completing the work. See https://github.com/Pylons/webob/pull/338 and
+  https://github.com/Pylons/webob/pull/335. 
+
+  If you were previously using the ``Accept`` class or the ``MIMEAccept`` class
+  directly, please take a look at the documentation for
+  :func:`~webob.acceptparse.create_accept_header`,
+  :func:`~webob.acceptparse.create_accept_charset_header`,
+  :func:`~webob.acceptparse.create_accept_encoding_header` and
+  :func:`~webob.acceptparse.create_accept_language_header`.
+
+  These functions will accept a header value and create the appropriate object.
+
+  The :ref:`API documentation for Accept* <acceptheader>` provides more
+  information on the available API.
+  
+- When calling a ``@wsgify`` decorated function, the default arguments passed
+  to ``@wsgify`` are now used when called with the request, and not as a
+  `start_response`
+
+  .. code::
+
+     def hello(req, name):
+         return "Hello, %s!" % name
+     app = wsgify(hello, args=("Fred",))
+
+     req = Request.blank('/')
+     resp = req.get_response(app)  # => "Hello, Fred"
+     resp2 = app(req) # => "Hello, Fred"
+
+  Previously the ``resp2`` line would have failed with a ``TypeError``. With
+  this change there is no way to override the default arguments with no
+  arguments. See https://github.com/Pylons/webob/pull/203
+
+- When setting ``app_iter`` on a ``Response`` object the ``content_md5`` header
+  is no longer cleared. This behaviour is odd and disallows setting the
+  ``content_md5`` and then returning an iterator for chunked content encoded
+  responses. See https://github.com/Pylons/webob/issues/86
+
+Experimental Features
+~~~~~~~~~~~~~~~~~~~~~
+
+These features are experimental and may change at any point in the future. The
+main page provides a list of :ref:`experimental-api` supported by WebOb.
+
+- The cookie APIs now have the ability to set the SameSite attribute on a
+  cookie in both :func:`webob.cookies.make_cookie` and
+  :class:`webob.cookies.CookieProfile`. See
+  https://github.com/Pylons/webob/pull/255
+
+  
+Bugfix
+~~~~~~
+
+- :attr:`Request.host_url <webob.request.BaseRequest.host_url>`,
+  :attr:`Request.host_port <webob.request.BaseRequest.host_port>`,
+  :attr:`Request.domain <webob.request.BaseRequest.domain>` correctly parse
+  IPv6 Host headers as provided by a browser. See
+  https://github.com/Pylons/webob/pull/332
+
+- :attr:`Request.authorization <webob.request.BaseRequest.authorization>` would
+  raise :class:`ValueError` for unusual or malformed header
+  values. Now it simply returns an empty value. See
+  https://github.com/Pylons/webob/issues/231
+
+- Allow unnamed fields in form data to be properly transcoded when calling
+  :func:`request.decode <webob.request.BaseRequest.decode>` with an alternate
+  encoding. See https://github.com/Pylons/webob/pull/309
+
+- :class:`Response.__init__ <webob.response.Response>` would discard
+  ``app_iter`` when a ``Response`` had no body, this would cause issues when
+  ``app_iter`` was an object that was tied to the life-cycle of a web
+  application and had to be properly closed. ``app_iter`` is more advanced API
+  for ``Response`` and thus even if it contains a body and is thus against the
+  HTTP RFC's, we should let the users shoot themselves in the foot by returning
+  a body. See https://github.com/Pylons/webob/issues/305
+