Add a what's new document.

1 files changed, 201 insertions, 0 deletions

diff --git a/docs/whatsnew-1.2.rst b/docs/whatsnew-1.2.rst
new file mode 100644
index 000000000..01ea7cec7
--- /dev/null
+++ b/docs/whatsnew-1.2.rst
@@ -0,0 +1,201 @@
+What's New In :mod:`repoze.bfg` 1.2
+===================================
+
+This article explains the new features in :mod:`repoze.bfg` version
+1.2 as compared to the previous 1.1 release.  It also documents
+backwards incompatibilities between the two versions and deprecations
+added to 1.2, as well as software dependency changes and notable
+documentation additions.
+
+Major Feature Additions
+-----------------------
+
+The major feature additions of 1.2 are:
+
+- An :term:`imperative configuration` mode.  This feature makes
+  :mod:`repoze.bfg` competetive with "microframeworks" such as `Bottle
+  <http://bottle.paws.de/>`_ and `Tornado
+  <http://www.tornadoweb.org/>`_, because it means that
+  :mod:`repoze.bfg` applications can begin life as a single file.
+  Later, the application may evolve into a package, and may start
+  making use of other configuration features, such as :term:`ZCML`.
+  :mod:`repoze.bfg` has a good deal of functionality that
+  microframeworks lack, so this is meant as a a "best of both worlds"
+  feature.
+
+  As a result of :term:`imperative configuration`, the simplest
+  possible :mod:`repoze.bfg` application is now:
+
+    .. code-block:: python
+       :linenos:
+
+       from webob import Response
+       from wsgiref import simple_server
+       from repoze.bfg.configuration import Configurator
+
+       def hello_world(request):
+           return Response('Hello world!')
+
+       if __name__ == '__main__':
+           config = Configurator()
+           config.add_view(hello_world)
+           app = config.make_wsgi_app()
+           simple_server.make_server('', 8080, app).serve_forever()
+
+  For an introduction to imperative-mode configuration, see
+  :ref:`configuration_narr`.
+
+Miscellaneous Minor Feature Additions
+--------------------------------------
+
+- The ``repoze.bfg.testing.setUp`` function now accepts three extra
+  optional keyword arguments: ``registry``, ``request`` and
+  ``hook_zca``.
+
+  If the ``registry`` argument is not ``None``, the argument will be
+  treated as the registry that is set as the "current registry" (it
+  will be returned by ``repoze.bfg.threadlocal.get_current_registry``)
+  for the duration of the test.  If the ``registry`` argument is
+  ``None`` (the default), a new registry is created and used for the
+  duration of the test.
+
+  The value of the ``request`` argument is used as the "current
+  request" (it will be returned by
+  ``repoze.bfg.threadlocal.get_current_request``) for the duration of
+  the test; it defaults to ``None``.
+
+  If ``hook_zca`` is ``True`` (the default), the
+  ``zope.component.getSiteManager`` function will be hooked with a
+  function that returns the value of ``registry`` (or the
+  default-created registry if ``registry`` is ``None``) instead of the
+  registry returned by ``zope.component.getGlobalSiteManager``,
+  causing the Zope Component Architecture API (``getSiteManager``,
+  ``getAdapter``, ``getUtility``, and so on) to use the registry we're
+  using for testing instead of the global ZCA registry.
+
+- The ``repoze.bfg.testing.tearDown`` function now accepts an
+  ``unhook_zca`` argument.  If this argument is ``True`` (the
+  default), ``zope.component.getSiteManager.reset()`` will be called,
+  causing the "base" registry to once again start returnining the
+  result of ``zope.component.getSiteManager``.
+
+Documentation
+-------------
+
+- The documentation now uses the "request-only" view calling
+  convention in most examples (as opposed to the ``context, request``
+  convention).  This is a documentation-only change; the ``context,
+  request`` convention is also supported and documented, and will be
+  "forever".
+
+- ``repoze.bfg.configuration`` API documentation has been added.
+
+- A narrative documentation chapter entitled "Creating Your First
+  ``repoze.bfg`` Application" has been added.  This chapter details
+  usage of the new ``repoze.bfg.configuration.Configurator`` class,
+  and demonstrates a simplified "imperative-mode" configuration; doing
+  ``repoze.bfg`` application configuration imperatively was previously
+  much more difficult.
+
+- A narrative documentation chapter entitled "Configuration,
+  Decorations and Code Scanning" explaining ZCML- vs. imperative-
+  vs. decorator-based configuration equivalence.
+
+- The "ZCML Hooks" chapter has been renamed to "Hooks"; it documents
+  how to override hooks now via imperative configuration and ZCML.
+
+- The explanation about how to supply an alternate "response factory"
+  has been removed from the "Hooks" chapter.  This feature may be
+  removed in a later release (it still works now, it's just not
+  documented).
+
+- Add a section entitled "Test Set Up and Tear Down" to the
+  unittesting chapter.
+
+Bug Fixes
+----------
+
+- The ACL authorization policy debugging output when
+  ``debug_authorization`` console debugging output was turned on
+  wasn't as clear as it could have been when a view execution was
+  denied due to an authorization failure resulting from the set of
+  principals passed never having matched any ACE in any ACL in the
+  lineage.  Now in this case, we report ``<default deny>`` as the ACE
+  value and either the root ACL or ``<No ACL found on any object in
+  model lineage>`` if no ACL was found.
+
+- When two views were registered with the same ``accept`` argument,
+  but were otherwise registered with the same arguments, if a request
+  entered the application which had an ``Accept`` header that accepted
+  *either* of the media types defined by the set of views registered
+  with predicates that otherwise matched, a more or less "random" one
+  view would "win".  Now, we try harder to use the view callable
+  associated with the view configuration that has the most specific
+  ``accept`` argument.  Thanks to Alberto Valverde for an initial
+  patch.
+
+Backwards Incompatibilites
+--------------------------
+
+- View registration no longer registers a
+  ``repoze.bfg.interfaces.IViewPermission`` adapter (it is no longer
+  checked by the framework; since 1.1, views have been responsible for
+  providing their own security).
+
+- The ``repoze.bfg.router.make_app`` callable no longer accepts the
+  ``authentication_policy`` nor the ``authorization_policy``
+  arguments.  This feature was deprecated in version 1.0 and has been
+  removed.
+
+- Obscure: the machinery which configured views with a
+  ``request_type`` *and* a ``route_name`` would ignore the request
+  interface implied by ``route_name`` registering a view only for the
+  interface implied by ``request_type``.  In the unlikely event that
+  you were trying to use these two features together, the symptom
+  would have been that views that named a ``request_type`` but which
+  were also associated with routes were not found when the route
+  matched.  Now if a view is configured with both a ``request_type``
+  and a ``route_name``, an error is raised.
+
+- The ``route`` ZCML directive now no longer accepts the
+  ``request_type`` or ``view_request_type`` attributes.  These
+  attributes didn't actually work in any useful way (see entry above
+  this one).
+
+- Because the ``repoze.bfg`` package now includes implementations of
+  the ``adapter``, ``subscriber`` and ``utility`` ZCML directives, it
+  is now an error to have ``<include package="repoze.zcml"
+  file="meta.zcml"/>`` in the ZCML of a ``repoze.bfg`` application.  A
+  ZCML conflict error will be raised if your ZCML does so.  This
+  shouldn't be an issue for "normal" installations; it has always been
+  the responsibility of the ``repoze.bfg.includes`` ZCML to include
+  this file in the past; it now just doesn't.
+
+- The ``repoze.bfg.testing.zcml_configure`` API was removed.  Use
+  the ``Configurator.load_zcml`` API instead.
+
+Deprecations
+------------
+
+- The ``repoze.bfg.router.make_app`` function is now nominally
+  deprecated.  Its import and usage does not throw a warning, nor will
+  it probably ever disappear.  However, using a
+  ``repoze.bfg.configuration.Configurator`` class is now the preferred
+  way to generate a WSGI application.
+
+  Note that ``make_app`` calls
+  ``zope.component.getSiteManager.sethook(
+  repoze.bfg.threadlocal.get_current_registry)`` on the caller's
+  behalf, hooking ZCA global API lookups, for backwards compatibility
+  purposes.  If you disuse ``make_app``, your calling code will need
+  to perform this call itself, at least if your application uses the
+  ZCA global API (``getSiteManager``, ``getAdapter``, etc).
+
+Dependencies
+------------
+
+- A dependency on the ``martian`` package has been removed (its
+  functionality is replaced internally).
+
+- A dependency on the ``repoze.zcml`` package has been removed (its
+  functionality is replaced internally).