Mark changelogs as ReST, for better Github rendering.

1 files changed, 6373 insertions, 0 deletions

diff --git a/BFG_HISTORY.rst b/BFG_HISTORY.rst
new file mode 100644
index 000000000..8a2d40920
--- /dev/null
+++ b/BFG_HISTORY.rst
@@ -0,0 +1,6373 @@
+1.3b1 (2010-10-25)
+==================
+
+Features
+--------
+
+- The ``paster`` template named ``bfg_routesalchemy`` has been updated
+  to use SQLAlchemy declarative syntax.  Thanks to Ergo^.
+
+Bug Fixes
+---------
+
+- When a renderer factory could not be found, a misleading error
+  message was raised if the renderer name was not a string.
+
+Documentation
+-------------
+
+- The ""bfgwiki2" (SQLAlchemy + url dispatch) tutorial has been
+  updated slightly.  In particular, the source packages no longer
+  attempt to use a private index, and the recommended Python version
+  is now 2.6.  It was also updated to take into account the changes to
+  the ``bfg_routesalchemy`` template used to set up an environment.
+
+- The "bfgwiki" (ZODB + traversal) tutorial has been updated slightly.
+  In particular, the source packages no longer attempt to use a
+  private index, and the recommended Python version is now 2.6.
+
+1.3a15 (2010-09-30)
+===================
+
+Features
+--------
+
+- The ``repoze.bfg.traversal.traversal_path`` API now eagerly attempts
+  to encode a Unicode ``path`` into ASCII before attempting to split
+  it and decode its segments.  This is for convenience, effectively to
+  allow a (stored-as-Unicode-in-a-database, or
+  retrieved-as-Unicode-from-a-request-parameter) Unicode path to be
+  passed to ``find_model``, which eventually internally uses the
+  ``traversal_path`` function under the hood.  In version 1.2 and
+  prior, if the ``path`` was Unicode, that Unicode was split on
+  slashes and each resulting segment value was Unicode.  An
+  inappropriate call to the ``decode()`` method of a resulting Unicode
+  path segment could cause a ``UnicodeDecodeError`` to occur even if
+  the Unicode representation of the path contained no 'high order'
+  characters (it effectively did a "double decode").  By converting
+  the Unicode path argument to ASCII before we attempt to decode and
+  split, genuine errors will occur in a more obvious place while also
+  allowing us to handle (for convenience) the case that it's a Unicode
+  representation formed entirely from ASCII-compatible characters.
+
+1.3a14 (2010-09-14)
+===================
+
+Bug Fixes
+---------
+
+- If an exception view was registered through the legacy
+  ``set_notfound_view`` or ``set_forbidden_view`` APIs, the context
+  sent to the view was incorrect (could be ``None`` inappropriately).
+
+Features
+--------
+
+- Compatibility with WebOb 1.0.
+
+Requirements
+------------
+
+- Now requires WebOb >= 1.0.
+
+Backwards Incompatibilities
+---------------------------
+
+- Due to changes introduced WebOb 1.0, the
+  ``repoze.bfg.request.make_request_ascii`` event subscriber no longer
+  works, so it has been removed.  This subscriber was meant to be used
+  in a deployment so that code written before BFG 0.7.0 could run
+  unchanged.  At this point, such code will need to be rewritten to
+  expect Unicode from ``request.GET``, ``request.POST`` and
+  ``request.params`` or it will need to be changed to use
+  ``request.str_POST``, ``request.str_GET`` and/or
+  ``request.str_params`` instead of the non-``str`` versions of same,
+  as the non-``str`` versions of the same APIs always now perform
+  decoding to Unicode.
+
+Errata
+------
+
+- A prior changelog entry asserted that the ``INewResponse`` event was
+  not sent to listeners if the response was not "valid" (if a view or
+  renderer returned a response object that did not have a
+  status/headers/app_iter).  This is not true in this release, nor was
+  it true in 1.3a13.
+
+1.3a13 (2010-09-14)
+===================
+
+Bug Fixes
+---------
+
+- The ``traverse`` route predicate could not successfully generate a
+  traversal path.
+
+Features
+--------
+
+- In support of making it easier to configure applications which are
+  "secure by default", a default permission feature was added.  If
+  supplied, the default permission is used as the permission string to
+  all view registrations which don't otherwise name a permission.
+  These APIs are in support of that:
+
+  - A new constructor argument was added to the Configurator:
+    ``default_permission``.
+
+  - A new method was added to the Configurator:
+    ``set_default_permission``.
+
+  - A new ZCML directive was added: ``default_permission``.
+
+- Add a new request API: ``request.add_finished_callback``.  Finished
+  callbacks are called by the router unconditionally near the very end
+  of request processing.  See the "Using Finished Callbacks" section
+  of the "Hooks" narrative chapter of the documentation for more
+  information.
+
+- A ``request.matched_route`` attribute is now added to the request
+  when a route has matched.  Its value is the "route" object that
+  matched (see the ``IRoute`` interface within
+  ``repoze.bfg.interfaces`` API documentation for the API of a route
+  object).
+
+- The ``exception`` attribute of the request is now set slightly
+  earlier and in a slightly different set of scenarios, for benefit of
+  "finished callbacks" and "response callbacks".  In previous
+  versions, the ``exception`` attribute of the request was not set at
+  all if an exception view was not found.  In this version, the
+  ``request.exception`` attribute is set immediately when an exception
+  is caught by the router, even if an exception view could not be
+  found.
+
+- The ``add_route`` method of a Configurator now accepts a
+  ``pregenerator`` argument.  The pregenerator for the resulting route
+  is called by ``route_url`` in order to adjust the set of arguments
+  passed to it by the user for special purposes, such as Pylons
+  'subdomain' support.  It will influence the URL returned by
+  ``route_url``.  See the ``repoze.bfg.interfaces.IRoutePregenerator``
+  interface for more information.
+
+Backwards Incompatibilities
+---------------------------
+
+- The router no longer sets the value ``wsgiorg.routing_args`` into
+  the environ when a route matches. The value used to be something
+  like ``((), matchdict)``.  This functionality was only ever
+  obliquely referred to in change logs; it was never documented as an
+  API.
+
+- The ``exception`` attribute of the request now defaults to ``None``.
+  In prior versions, the ``request.exception`` attribute did not exist
+  if an exception was not raised by user code during request
+  processing; it only began existence once an exception view was
+  found.
+
+Deprecations
+------------
+
+- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event
+  interface was renamed to
+  ``repoze.bfg.interfaces.IApplicationCreated``.  Likewise, the
+  ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed
+  to ``repoze.bfg.events.ApplicationCreated``.  The older aliases will
+  continue to work indefinitely.
+
+- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was
+  renamed to ``repoze.bfg.interfaces.IContextFound``.  Likewise, the
+  ``repoze.bfg.events.AfterTraversal`` class was renamed to
+  ``repoze.bfg.events.ContextFound``.  The older aliases will continue
+  to work indefinitely.
+
+- References to the WSGI environment values ``bfg.routes.matchdict``
+  and ``bfg.routes.route`` were removed from documentation.  These
+  will stick around internally for several more releases, but it is
+  ``request.matchdict`` and ``request.matched_route`` are now the
+  "official" way to obtain the matchdict and the route object which
+  resulted in the match.
+
+Documentation
+-------------
+
+- Added documentation for the ``default_permission`` ZCML directive.
+
+- Added documentation for the ``default_permission`` constructor value
+  and the ``set_default_permission`` method in the Configurator API
+  documentation.
+
+- Added a new section to the "security" chapter named "Setting a
+  Default Permission".
+
+- Document ``renderer_globals_factory`` and ``request_factory``
+  arguments to Configurator constructor.
+
+- Added two sections to the "Hooks" chapter of the documentation:
+  "Using Response Callbacks" and "Using Finished Callbacks".
+
+- Added documentation of the ``request.exception`` attribute to the
+  ``repoze.bfg.request.Request`` API documentation.
+
+- Added glossary entries for "response callback" and "finished
+  callback".
+
+- The "Request Processing" narrative chapter has been updated to note
+  finished and response callback steps.
+
+- New interface in interfaces API documentation: ``IRoutePregenerator``.
+
+- Added a "The Matched Route" section to the URL Dispatch narrative
+  docs chapter, detailing the ``matched_route`` attribute.
+
+1.3a12 (2010-09-08)
+===================
+
+Bug Fixes
+---------
+
+- Fix a bug in ``repoze.bfg.url.static_url`` URL generation: if two
+  resource specifications were used to create two separate static
+  views, but they shared a common prefix, it was possible that
+  ``static_url`` would generate an incorrect URL.
+
+- Fix another bug in ``repoze.bfg.static_url`` URL generation: too
+  many slashes in generated URL.
+
+- Prevent a race condition which could result in a ``RuntimeError``
+  when rendering a Chameleon template that has not already been
+  rendered once.  This would usually occur directly after a restart,
+  when more than one person or thread is trying to execute the same
+  view at the same time: https://bugs.launchpad.net/karl3/+bug/621364
+
+Features
+--------
+
+- The argument to ``repoze.bfg.configuration.Configurator.add_route``
+  which was previously called ``path`` is now called ``pattern`` for
+  better explicability.  For backwards compatibility purposes, passing
+  a keyword argument named ``path`` to ``add_route`` will still work
+  indefinitely.
+
+- The ``path`` attribute to the ZCML ``route`` directive is now named
+  ``pattern`` for better explicability.  The older ``path`` attribute
+  will continue to work indefinitely.
+
+Documentation
+-------------
+
+- All narrative, API, and tutorial docs which referred to a route
+  pattern as a ``path`` have now been updated to refer to them as a
+  ``pattern``.
+
+- The ``repoze.bfg.interfaces`` API documentation page is now rendered
+  via ``repoze.sphinx.autointerface``.
+
+- The URL Dispatch narrative chapter now refers to the ``interfaces``
+  chapter to explain the API of an ``IRoute`` object.
+
+Paster Templates
+----------------
+
+- The routesalchemy template has been updated to use ``pattern`` in
+  its route declarations rather than ``path``.
+
+Dependencies
+------------
+
+- ``tests_require`` now includes ``repoze.sphinx.autointerface`` as a
+  dependency.
+
+Internal
+--------
+
+- Add an API to the ``Configurator`` named ``get_routes_mapper``.
+  This returns an object implementing the ``IRoutesMapper`` interface.
+
+- The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a
+  ``get_route`` method which returns a single Route object or
+  ``None``.
+
+- A new interface ``repoze.bfg.interfaces.IRoute`` was added.  The
+  ``repoze.bfg.urldispatch.Route`` object implements this interface.
+
+- The canonical attribute for accessing the routing pattern from a
+  route object is now ``pattern`` rather than ``path``.
+
+- Use ``hash()`` rather than ``id()`` when computing the "phash" of a
+  custom route/view predicate in order to allow the custom predicate
+  some control over which predicates are "equal".
+
+- Use ``response.headerlist.append`` instead of
+  ``response.headers.add`` in
+  ``repoze.bfg.request.add_global_response_headers`` in case the
+  response is not a WebOb response.
+
+- The ``repoze.bfg.urldispatch.Route`` constructor (not an API) now
+  accepts a different ordering of arguments.  Previously it was
+  ``(pattern, name, factory=None, predicates=())``.  It is now
+  ``(name, pattern, factory=None, predicates=())``.  This is in
+  support of consistency with ``configurator.add_route``.
+
+- The ``repoze.bfg.urldispatch.RoutesMapper.connect`` method (not an
+  API) now accepts a different ordering of arguments.  Previously it
+  was ``(pattern, name, factory=None, predicates=())``.  It is now
+  ``(name, pattern, factory=None, predicates=())``.  This is in
+  support of consistency with ``configurator.add_route``.
+
+1.3a11 (2010-09-05)
+===================
+
+Bug Fixes
+---------
+
+- Process the response callbacks and the NewResponse event earlier, to
+  enable mutations to the response to take effect.
+
+1.3a10 (2010-09-05)
+===================
+
+Features
+--------
+
+- A new ``repoze.bfg.request.Request.add_response_callback`` API has
+  been added.  This method is documented in the new
+  ``repoze.bfg.request`` API chapter.  It can be used to influence
+  response values before a concrete response object has been created.
+
+- The ``repoze.bfg.interfaces.INewResponse`` interface now includes a
+  ``request`` attribute; as a result, a handler for INewResponse now
+  has access to the request which caused the response.
+
+- Each of the follow methods of the Configurator now allow the
+  below-named arguments to be passed as "dotted name strings"
+  (e.g. "foo.bar.baz") rather than as actual implementation objects
+  that must be imported:
+
+  setup_registry
+     root_factory, authentication_policy, authorization_policy,
+     debug_logger, locale_negotiator, request_factory,
+     renderer_globals_factory
+
+  add_subscriber
+     subscriber, iface
+
+  derive_view
+     view
+
+  add_view
+     view, ``for_``, context, request_type, containment
+
+  add_route()
+     view, view_for, factory, ``for_``, view_context
+
+  scan
+     package
+
+  add_renderer
+     factory
+
+  set_forbidden_view
+     view
+
+  set_notfound_view
+     view
+
+  set_request_factory
+     factory
+
+  set_renderer_globals_factory()
+     factory
+
+  set_locale_negotiator
+     negotiator
+
+  testing_add_subscriber
+     event_iface
+
+Bug Fixes
+---------
+
+- The route pattern registered internally for a local "static view"
+  (either via the ``static`` ZCML directive or via the
+  ``add_static_view`` method of the configurator) was incorrect.  It
+  was regsistered for e.g. ``static*traverse``, while it should have
+  been registered for ``static/*traverse``.  Symptom: two static views
+  could not reliably be added to a system when they both shared the
+  same path prefix (e.g. ``/static`` and ``/static2``).
+
+Backwards Incompatibilities
+---------------------------
+
+- The INewResponse event is now not sent to listeners if the response
+  returned by view code (or a renderer) is not a "real" response
+  (e.g. if it does not have ``.status``, ``.headerlist`` and
+  ``.app_iter`` attribtues).
+
+Documentation
+-------------
+
+- Add an API chapter for the ``repoze.bfg.request`` module, which
+  includes documentation for the ``repoze.bfg.request.Request`` class
+  (the "request object").
+
+- Modify the "Request and Response" narrative chapter to reference the
+  new ``repoze.bfg.request`` API chapter.  Some content was moved from
+  this chapter into the API documentation itself.
+
+- Various changes to denote that Python dotted names are now allowed
+  as input to Configurator methods.
+
+Internal
+--------
+
+- The (internal) feature which made it possible to attach a
+  ``global_response_headers`` attribute to the request (which was
+  assumed to contain a sequence of header key/value pairs which would
+  later be added to the response by the router), has been removed.
+  The functionality of
+  ``repoze.bfg.request.Request.add_response_callback`` takes its
+  place.
+
+- The ``repoze.bfg.events.NewResponse`` class's construct has changed:
+  it now must be created with ``(request, response)`` rather than
+  simply ``(response)``.
+
+1.3a9 (2010-08-22)
+==================
+
+Features
+--------
+
+- The Configurator now accepts a dotted name *string* to a package as
+  a ``package`` constructor argument. The ``package`` argument was
+  previously required to be a package *object* (not a dotted name
+  string).
+
+- The ``repoze.bfg.configuration.Configurator.with_package`` method
+  was added.  This method returns a new Configurator using the same
+  application registry as the configurator object it is called
+  upon. The new configurator is created afresh with its ``package``
+  constructor argument set to the value passed to ``with_package``.
+  This feature will make it easier for future BFG versions to allow
+  dotted names as arguments in places where currently only object
+  references are allowed (the work to allow dotted names isntead of
+  object references everywhere has not yet been done, however).
+
+- The new ``repoze.bfg.configuration.Configurator.maybe_dotted``
+  method resolves a Python dotted name string supplied as its
+  ``dotted`` argument to a global Python object.  If the value cannot
+  be resolved, a ``repoze.bfg.configuration.ConfigurationError`` is
+  raised.  If the value supplied as ``dotted`` is not a string, the
+  value is returned unconditionally without any resolution attempted.
+
+- The new
+  ``repoze.bfg.configuration.Configurator.absolute_resource_spec``
+  method resolves a potentially relative "resource specification"
+  string into an absolute version.  If the value supplied as
+  ``relative_spec`` is not a string, the value is returned
+  unconditionally without any resolution attempted.
+
+Backwards Incompatibilities
+---------------------------
+
+- The functions in ``repoze.bfg.renderers`` named ``render`` and
+  ``render_to_response`` introduced in 1.3a6 previously took a set of
+  ``**values`` arguments for the values to be passed to the renderer.
+  This was wrong, as renderers don't need to accept only dictionaries
+  (they can accept any type of object).  Now, the value sent to the
+  renderer must be supplied as a positional argument named ``value``.
+  The ``request`` argument is still a keyword argument, however.
+
+- The functions in ``repoze.bfg.renderers`` named ``render`` and
+  ``render_to_response`` now accept an additonal keyword argument
+  named ``package``.
+
+- The ``get_renderer`` API in ``repoze.bfg.renderers`` now accepts a
+  ``package`` argument.
+
+Documentation
+-------------
+
+- The ZCML ``include`` directive docs were incorrect: they specified
+  ``filename`` rather than (the correct) ``file`` as an allowable
+  attribute.
+
+Internal
+--------
+
+- The ``repoze.bfg.resource.resolve_resource_spec`` function can now
+  accept a package object as its ``pname`` argument instead of just a
+  package name.
+
+- The ``_renderer_factory_from_name`` and ``_renderer_from_name``
+  methods of the Configurator were removed.  These were never APIs.
+
+- The ``_render``, ``_render_to_response`` and ``_make_response``
+  functions with ``repoze.bfg.render`` (added in 1.3a6) have been
+  removed.
+
+- A new helper class ``repoze.bfg.renderers.RendererHelper`` was
+  added.
+
+- The _map_view function of ``repoze.bfg.configuration`` now takes
+  only a renderer_name argument instead of both a ``renderer`` and
+  ``renderer``_name argument.  It also takes a ``package`` argument
+  now.
+
+- Use ``imp.get_suffixes`` indirection in
+  ``repoze.bfg.path.package_name`` instead of hardcoded ``.py``
+  ``.pyc`` and ``.pyo`` to use for comparison when attemtping to
+  decide if a directory is a package.
+
+- Make tests runnable again under Jython (although they do not all
+  pass currently).
+
+- The reify decorator now maintains the docstring of the function it
+  wraps.
+
+1.3a8 (2010-08-08)
+==================
+
+Features
+--------
+
+- New public interface: ``repoze.bfg.exceptions.IExceptionResponse``.
+  This interface is provided by all internal exception classes (such
+  as ``repoze.bfg.exceptions.NotFound`` and
+  ``repoze.bfg.exceptions.Forbidden``), instances of which are both
+  exception objects and can behave as WSGI response objects.  This
+  interface is made public so that exception classes which are also
+  valid WSGI response factories can be configured to implement them or
+  exception instances which are also or response instances can be
+  configured to provide them.
+
+- New API class: ``repoze.bfg.view.AppendSlashNotFoundViewFactory``.
+
+  There can only be one Not Found view in any ``repoze.bfg``
+  application.  Even if you use
+  ``repoze.bfg.view.append_slash_notfound_view`` as the Not Found
+  view, ``repoze.bfg`` still must generate a ``404 Not Found``
+  response when it cannot redirect to a slash-appended URL; this not
+  found response will be visible to site users.
+
+  If you don't care what this 404 response looks like, and you only
+  need redirections to slash-appended route URLs, you may use the
+  ``repoze.bfg.view.append_slash_notfound_view`` object as the Not
+  Found view.  However, if you wish to use a *custom* notfound view
+  callable when a URL cannot be redirected to a slash-appended URL,
+  you may wish to use an instance of the
+  ``repoze.bfg.view.AppendSlashNotFoundViewFactory`` class as the Not
+  Found view, supplying the notfound view callable as the first
+  argument to its constructor.  For instance::
+
+       from repoze.bfg.exceptions import NotFound
+       from repoze.bfg.view import AppendSlashNotFoundViewFactory
+
+       def notfound_view(context, request):
+           return HTTPNotFound('It aint there, stop trying!')
+
+       custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
+       config.add_view(custom_append_slash, context=NotFound)
+
+  The ``notfound_view`` supplied must adhere to the two-argument view
+  callable calling convention of ``(context, request)`` (``context``
+  will be the exception object).
+
+Documentation
+--------------
+
+- Expanded the "Cleaning Up After a Request" section of the URL
+  Dispatch narrative chapter.
+
+- Expanded the "Redirecting to Slash-Appended Routes" section of the
+  URL Dispatch narrative chapter.
+
+Internal
+--------
+
+- Previously, two default view functions were registered at
+  Configurator setup (one for ``repoze.bfg.exceptions.NotFound`` named
+  ``default_notfound_view`` and one for
+  ``repoze.bfg.exceptions.Forbidden`` named
+  ``default_forbidden_view``) to render internal exception responses.
+  Those default view functions have been removed, replaced with a
+  generic default view function which is registered at Configurator
+  setup for the ``repoze.bfg.interfaces.IExceptionResponse`` interface
+  that simply returns the exception instance; the ``NotFound`` and
+  ``Forbidden`` classes are now still exception factories but they are
+  also response factories which generate instances that implement the
+  new ``repoze.bfg.interfaces.IExceptionResponse`` interface.
+
+1.3a7 (2010-08-01)
+==================
+
+Features
+--------
+
+- The ``repoze.bfg.configuration.Configurator.add_route`` API now
+  returns the route object that was added.
+
+- A ``repoze.bfg.events.subscriber`` decorator was added.  This
+  decorator decorates module-scope functions, which are then treated
+  as event listeners after a scan() is performed.  See the Events
+  narrative documentation chapter and the ``repoze.bfg.events`` module
+  documentation for more information.
+
+Bug Fixes
+---------
+
+- When adding a view for a route which did not yet exist ("did not yet
+  exist" meaning, temporally, a view was added with a route name for a
+  route which had not yet been added via add_route), the value of the
+  ``custom_predicate`` argument to ``add_view`` was lost.  Symptom:
+  wrong view matches when using URL dispatch and custom view
+  predicates together.
+
+- Pattern matches for a ``:segment`` marker in a URL dispatch route
+  pattern now always match at least one character.  See "Backwards
+  Incompatibilities" below in this changelog.
+
+Backwards Incompatibilities
+---------------------------
+
+- A bug existed in the regular expression to do URL matching.  As an
+  example, the URL matching machinery would cause the pattern
+  ``/{foo}`` to match the root URL ``/`` resulting in a match
+  dictionary of ``{'foo':u''}`` or the pattern ``/{fud}/edit might
+  match the URL ``//edit`` resulting in a match dictionary of
+  ``{'fud':u''}``.  It was always the intent that ``:segment`` markers
+  in the pattern would need to match *at least one* character, and
+  never match the empty string.  This, however, means that in certain
+  circumstances, a routing match which your application inadvertently
+  depended upon may no longer happen.
+
+Documentation
+--------------
+
+- Added description of the ``repoze.bfg.events.subscriber`` decorator
+  to the Events narrative chapter.
+
+- Added ``repoze.bfg.events.subscriber`` API documentation to
+  ``repoze.bfg.events`` API docs.
+
+- Added a section named "Zope 3 Enforces 'TTW' Authorization Checks By
+  Default; BFG Does Not" to the "Design Defense" chapter.
+
+1.3a6 (2010-07-25)
+==================
+
+Features
+--------
+
+- New argument to ``repoze.bfg.configuration.Configurator.add_route``
+  and the ``route`` ZCML directive: ``traverse``.  If you would like
+  to cause the ``context`` to be something other than the ``root``
+  object when this route matches, you can spell a traversal pattern as
+  the ``traverse`` argument.  This traversal pattern will be used as
+  the traversal path: traversal will begin at the root object implied
+  by this route (either the global root, or the object returned by the
+  ``factory`` associated with this route).
+
+  The syntax of the ``traverse`` argument is the same as it is for
+  ``path``. For example, if the ``path`` provided is
+  ``articles/:article/edit``, and the ``traverse`` argument provided
+  is ``/:article``, when a request comes in that causes the route to
+  match in such a way that the ``article`` match value is '1' (when
+  the request URI is ``/articles/1/edit``), the traversal path will be
+  generated as ``/1``.  This means that the root object's
+  ``__getitem__`` will be called with the name ``1`` during the
+  traversal phase.  If the ``1`` object exists, it will become the
+  ``context`` of the request.  The Traversal narrative has more
+  information about traversal.
+
+  If the traversal path contains segment marker names which are not
+  present in the path argument, a runtime error will occur.  The
+  ``traverse`` pattern should not contain segment markers that do not
+  exist in the ``path``.
+
+  A similar combining of routing and traversal is available when a
+  route is matched which contains a ``*traverse`` remainder marker in
+  its path.  The ``traverse`` argument allows you to associate route
+  patterns with an arbitrary traversal path without using a
+  ``*traverse`` remainder marker; instead you can use other match
+  information.
+
+  Note that the ``traverse`` argument is ignored when attached to a
+  route that has a ``*traverse`` remainder marker in its path.
+
+- A new method of the ``Configurator`` exists:
+  ``set_request_factory``.  If used, this method will set the factory
+  used by the ``repoze.bfg`` router to create all request objects.
+
+- The ``Configurator`` constructor takes an additional argument:
+  ``request_factory``.  If used, this argument will set the factory
+  used by the ``repoze.bfg`` router to create all request objects.
+
+- The ``Configurator`` constructor takes an additional argument:
+  ``request_factory``.  If used, this argument will set the factory
+  used by the ``repoze.bfg`` router to create all request objects.
+
+- A new method of the ``Configurator`` exists:
+  ``set_renderer_globals_factory``.  If used, this method will set the
+  factory used by the ``repoze.bfg`` router to create renderer
+  globals.
+
+- A new method of the ``Configurator`` exists: ``get_settings``.  If
+  used, this method will return the current settings object (performs
+  the same job as the ``repoze.bfg.settings.get_settings`` API).
+
+- The ``Configurator`` constructor takes an additional argument:
+  ``renderer_globals_factory``.  If used, this argument will set the
+  factory used by the ``repoze.bfg`` router to create renderer
+  globals.
+
+- Add ``repoze.bfg.renderers.render``,
+  ``repoze.bfg.renderers.render_to_response`` and
+  ``repoze.bfg.renderers.get_renderer`` functions.  These are
+  imperative APIs which will use the same rendering machinery used by
+  view configurations with a ``renderer=`` attribute/argument to
+  produce a rendering or renderer.  Because these APIs provide a
+  central API for all rendering, they now form the preferred way to
+  perform imperative template rendering.  Using functions named
+  ``render_*`` from modules such as ``repoze.bfg.chameleon_zpt`` and
+  ``repoze.bfg.chameleon_text`` is now discouraged (although not
+  deprecated).  The code the backing older templating-system-specific
+  APIs now calls into the newer ``repoze.bfg.renderer`` code.
+
+- The ``repoze.bfg.configuration.Configurator.testing_add_template``
+  has been renamed to ``testing_add_renderer``.  A backwards
+  compatibility alias is present using the old name.
+
+Documentation
+-------------
+
+- The ``Hybrid`` narrative chapter now contains a description of the
+  ``traverse`` route argument.
+
+- The ``Hooks`` narrative chapter now contains sections about
+  changing the request factory and adding a renderer globals factory.
+
+- The API documentation includes a new module:
+  ``repoze.bfg.renderers``.
+
+- The ``Templates`` chapter was updated; all narrative that used
+  templating-specific APIs within examples to perform rendering (such
+  as the ``repoze.bfg.chameleon_zpt.render_template_to_response``
+  method) was changed to use ``repoze.bfg.renderers.render_*``
+  functions.
+
+Bug Fixes
+---------
+
+- The ``header`` predicate (when used as either a view predicate or a
+  route predicate) had a problem when specified with a name/regex
+  pair.  When the header did not exist in the headers dictionary, the
+  regex match could be fed ``None``, causing it to throw a
+  ``TypeError: expected string or buffer`` exception.  Now, the
+  predicate returns False as intended.
+
+Deprecations
+------------
+
+- The ``repoze.bfg.renderers.rendered_response`` function was never an
+  official API, but may have been imported by extensions in the wild.
+  It is officially deprecated in this release.  Use
+  ``repoze.bfg.renderers.render_to_response`` instead.
+
+- The following APIs are *documentation* deprecated (meaning they are
+  officially deprecated in documentation but do not raise a
+  deprecation error upon their usage, and may continue to work for an
+  indefinite period of time):
+
+  In the ``repoze.bfg.chameleon_zpt`` module: ``get_renderer``,
+  ``get_template``, ``render_template``,
+  ``render_template_to_response``.  The suggested alternatives are
+  documented within the docstrings of those methods (which are still
+  present in the documentation).
+
+  In the ``repoze.bfg.chameleon_text`` module: ``get_renderer``,
+  ``get_template``, ``render_template``,
+  ``render_template_to_response``.  The suggested alternatives are
+  documented within the docstrings of those methods (which are still
+  present in the documentation).
+
+  In general, to perform template-related functions, one should now
+  use the various methods in the ``repoze.bfg.renderers`` module.
+
+Backwards Incompatibilities
+---------------------------
+
+- A new internal exception class (*not* an API) named
+  ``repoze.bfg.exceptions.PredicateMismatch`` now exists.  This
+  exception is currently raised when no constituent view of a
+  multiview can be called (due to no predicate match).  Previously, in
+  this situation, a ``repoze.bfg.exceptions.NotFound`` was raised.  We
+  provide backwards compatibility for code that expected a
+  ``NotFound`` to be raised when no predicates match by causing
+  ``repoze.bfg.exceptions.PredicateMismatch`` to inherit from
+  ``NotFound``.  This will cause any exception view registered for
+  ``NotFound`` to be called when a predicate mismatch occurs, as was
+  the previous behavior.
+
+  There is however, one perverse case that will expose a backwards
+  incompatibility.  If 1) you had a view that was registered as a
+  member of a multiview 2) this view explicitly raised a ``NotFound``
+  exception *in order to* proceed to the next predicate check in the
+  multiview, that code will now behave differently: rather than
+  skipping to the next view match, a NotFound will be raised to the
+  top-level exception handling machinery instead.  For code to be
+  depending upon the behavior of a view raising ``NotFound`` to
+  proceed to the next predicate match, would be tragic, but not
+  impossible, given that ``NotFound`` is a public interface.
+  ``repoze.bfg.exceptions.PredicateMismatch`` is not a public API and
+  cannot be depended upon by application code, so you should not
+  change your view code to raise ``PredicateMismatch``.  Instead, move
+  the logic which raised the ``NotFound`` exception in the view out
+  into a custom view predicate.
+
+- If, when you run your application's unit test suite under BFG 1.3, a
+  ``KeyError`` naming a template or a ``ValueError`` indicating that a
+  'renderer factory' is not registered may is raised
+  (e.g. ``ValueError: No factory for renderer named '.pt' when looking
+  up karl.views:templates/snippets.pt``), you may need to perform some
+  extra setup in your test code.
+
+  The best solution is to use the
+  ``repoze.bfg.configuration.Configurator.testing_add_renderer`` (or,
+  alternately the deprecated
+  ``repoze.bfg.testing.registerTemplateRenderer`` or
+  ``registerDummyRenderer``) API within the code comprising each
+  individual unit test suite to register a "dummy" renderer for each
+  of the templates and renderers used by code under test.  For
+  example::
+
+    config = Configurator()
+    config.testing_add_renderer('karl.views:templates/snippets.pt')
+
+  This will register a basic dummy renderer for this particular
+  missing template.  The ``testing_add_renderer`` API actually
+  *returns* the renderer, but if you don't care about how the render
+  is used, you don't care about having a reference to it either.
+
+  A more rough way to solve the issue exists.  It causes the "real"
+  template implementations to be used while the system is under test,
+  which is suboptimal, because tests will run slower, and unit tests
+  won't actually *be* unit tests, but it is easier.  Always ensure you
+  call the ``setup_registry()`` method of the Configurator .  Eg::
+
+    reg = MyRegistry()
+    config = Configurator(registry=reg)
+    config.setup_registry()
+
+  Calling ``setup_registry`` only has an effect if you're *passing in*
+  a ``registry`` argument to the Configurator constructor.
+  ``setup_registry`` is called by the course of normal operations
+  anyway if you do not pass in a ``registry``.
+
+  If your test suite isn't using a Configurator yet, and is still
+  using the older ``repoze.bfg.testing`` APIs name ``setUp`` or
+  ``cleanUp``, these will register the renderers on your behalf.
+
+  A variant on the symptom for this theme exists: you may already be
+  dutifully registering a dummy template or renderer for a template
+  used by the code you're testing using ``testing_register_renderer``
+  or ``registerTemplateRenderer``, but (perhaps unbeknownst to you)
+  the code under test expects to be able to use a "real" template
+  renderer implementation to retrieve or render *another* template
+  that you forgot was being rendered as a side effect of calling the
+  code you're testing.  This happened to work because it found the
+  *real* template while the system was under test previously, and now
+  it cannot.  The solution is the same.
+
+  It may also help reduce confusion to use a *resource specification*
+  to specify the template path in the test suite and code rather than
+  a relative path in either.  A resource specification is unambiguous,
+  while a relative path needs to be relative to "here", where "here"
+  isn't always well-defined ("here" in a test suite may or may not be
+  the same as "here" in the code under test).
+
+1.3a5 (2010-07-14)
+==================
+
+Features
+--------
+
+- New internal exception: ``repoze.bfg.exceptions.URLDecodeError``.
+  This URL is a subclass of the built-in Python exception named
+  ``UnicodeDecodeError``.
+
+- When decoding a URL segment to Unicode fails, the exception raised
+  is now ``repoze.bfg.exceptions.URLDecodeError`` instead of
+  ``UnicodeDecodeError``.  This makes it possible to register an
+  exception view invoked specifically when ``repoze.bfg`` cannot
+  decode a URL.
+
+Bug Fixes
+---------
+
+- Fix regression in
+  ``repoze.bfg.configuration.Configurator.add_static_view``.  Before
+  1.3a4, view names that contained a slash were supported as route
+  prefixes. 1.3a4 broke this by trying to treat them as full URLs.
+
+Documentation
+-------------
+
+- The ``repoze.bfg.exceptions.URLDecodeError`` exception was added to
+  the exceptions chapter of the API documentation.
+
+Backwards Incompatibilities
+----------------------------
+
+- in previous releases, when a URL could not be decoded from UTF-8
+  during traversal, a ``TypeError`` was raised.  Now the error which
+  is raised is a ``repoze.bfg.exceptions.URLDecodeError``.
+
+1.3a4 (2010-07-03)
+==================
+
+Features
+--------
+
+- Undocumented hook: make ``get_app`` and ``get_root`` of the
+  ``repoze.bfg.paster.BFGShellCommand`` hookable in cases where
+  endware may interfere with the default versions.
+
+- In earlier versions, a custom route predicate associated with a url
+  dispatch route (each of the predicate functions fed to the
+  ``custom_predicates`` argument of
+  ``repoze.bfg.configuration.Configurator.add_route``) has always
+  required a 2-positional argument signature, e.g. ``(context,
+  request)``.  Before this release, the ``context`` argument was
+  always ``None``.
+
+  As of this release, the first argument passed to a predicate is now
+  a dictionary conventionally named ``info`` consisting of ``route``,
+  and ``match``.  ``match`` is a dictionary: it represents the
+  arguments matched in the URL by the route.  ``route`` is an object
+  representing the route which was matched.
+
+  This is useful when predicates need access to the route match.  For
+  example::
+
+    def any_of(segment_name, *args):
+        def predicate(info, request):
+            if info['match'][segment_name] in args:
+                return True
+        return predicate
+
+    num_one_two_or_three = any_of('num, 'one', 'two', 'three')
+
+    add_route('num', '/:num', custom_predicates=(num_one_two_or_three,))
+
+  The ``route`` object is an object that has two useful attributes:
+  ``name`` and ``path``.  The ``name`` attribute is the route name.
+  The ``path`` attribute is the route pattern.  An example of using
+  the route in a set of route predicates::
+
+    def twenty_ten(info, request):
+        if info['route'].name in ('ymd', 'ym', 'y'):
+            return info['match']['year'] == '2010'
+
+    add_route('y', '/:year', custom_predicates=(twenty_ten,))
+    add_route('ym', '/:year/:month', custom_predicates=(twenty_ten,))
+    add_route('ymd', '/:year/:month:/day', custom_predicates=(twenty_ten,))
+
+- The ``repoze.bfg.url.route_url`` API has changed.  If a keyword
+  ``_app_url`` is present in the arguments passed to ``route_url``,
+  this value will be used as the protocol/hostname/port/leading path
+  prefix of the generated URL.  For example, using an ``_app_url`` of
+  ``http://example.com:8080/foo`` would cause the URL
+  ``http://example.com:8080/foo/fleeb/flub`` to be returned from this
+  function if the expansion of the route pattern associated with the
+  ``route_name`` expanded to ``/fleeb/flub``.
+
+- It is now possible to use a URL as the ``name`` argument fed to
+  ``repoze.bfg.configuration.Configurator.add_static_view``.  When the
+  name argument is a URL, the ``repoze.bfg.url.static_url`` API will
+  generate join this URL (as a prefix) to a path including the static
+  file name.  This makes it more possible to put static media on a
+  separate webserver for production, while keeping static media
+  package-internal and served by the development webserver during
+  development.
+
+Documentation
+-------------
+
+- The authorization chapter of the ZODB Wiki Tutorial
+  (docs/tutorials/bfgwiki) was changed to demonstrate authorization
+  via a group rather than via a direct username (thanks to Alex
+  Marandon).
+
+- The authorization chapter of the SQLAlchemy Wiki Tutorial
+  (docs/tutorials/bfgwiki2) was changed to demonstrate authorization
+  via a group rather than via a direct username.
+
+- Redirect requests for tutorial sources to
+  http://docs.repoze.org/bfgwiki-1.3 and
+  http://docs.repoze.org/bfgwiki2-1.3/ respectively.
+
+- A section named ``Custom Route Predicates`` was added to the URL
+  Dispatch narrative chapter.
+
+- The Static Resources chapter has been updated to mention using
+  ``static_url`` to generate URLs to external webservers.
+
+Internal
+--------
+
+- Removed ``repoze.bfg.static.StaticURLFactory`` in favor of a new
+  abstraction revolving around the (still-internal)
+  ``repoze.bfg.static.StaticURLInfo`` helper class.
+
+1.3a3 (2010-05-01)
+==================
+
+Paster Templates
+----------------
+
+- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer
+  register a ``handle_teardown`` event listener which calls
+  ``DBSession.remove``.  This was found by Chris Withers to be
+  unnecessary.
+
+Documentation
+-------------
+
+- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation
+  was changed to remove the ``handle_teardown`` event listener which
+  calls ``DBSession.remove``.
+
+- Any mention of the ``handle_teardown`` event listener as used by the
+  paster templates was removed from the URL Dispatch narrative chapter.
+
+- A section entitled Detecting Available Languages was added to the
+  i18n narrative docs chapter.
+
+1.3a2 (2010-04-28)
+==================
+
+Features
+--------
+
+- A locale negotiator no longer needs to be registered explicitly. The
+  default locale negotiator at
+  ``repoze.bfg.i18n.default_locale_negotiator`` is now used
+  unconditionally as... um, the default locale negotiator.
+
+- The default locale negotiator has become more complex.
+
+  * First, the negotiator looks for the ``_LOCALE_`` attribute of
+    the request object (possibly set by a view or an event listener).
+  
+  * Then it looks for the ``request.params['_LOCALE_']`` value.
+
+  * Then it looks for the ``request.cookies['_LOCALE_']`` value.
+
+Backwards Incompatibilities
+---------------------------
+
+- The default locale negotiator now looks for the parameter named
+  ``_LOCALE_`` rather than a parameter named ``locale`` in
+  ``request.params``.
+
+Behavior Changes
+----------------
+
+- A locale negotiator may now return ``None``, signifying that the
+  default locale should be used.
+
+Documentation
+-------------
+
+- Documentation concerning locale negotiation in the
+  Internationalizationa and Localization chapter was updated.
+
+- Expanded portion of i18n narrative chapter docs which discuss
+  working with gettext files.
+
+1.3a1 (2010-04-26)
+==================
+
+Features
+--------
+
+- Added "exception views".  When you use an exception (anything that
+  inherits from the Python ``Exception`` builtin) as view context
+  argument, e.g.::
+
+      from repoze.bfg.view import bfg_view
+      from repoze.bfg.exceptions import NotFound
+      from webob.exc import HTTPNotFound
+
+      @bfg_view(context=NotFound)
+      def notfound_view(request):
+          return HTTPNotFound()
+
+  For the above example, when the ``repoze.bfg.exceptions.NotFound``
+  exception is raised by any view or any root factory, the
+  ``notfound_view`` view callable will be invoked and its response
+  returned.
+
+  Other normal view predicates can also be used in combination with an
+  exception view registration::
+
+      from repoze.bfg.view import bfg_view
+      from repoze.bfg.exceptions import NotFound
+      from webob.exc import HTTPNotFound
+
+      @bfg_view(context=NotFound, route_name='home')
+      def notfound_view(request):
+          return HTTPNotFound()
+
+  The above exception view names the ``route_name`` of ``home``,
+  meaning that it will only be called when the route matched has a
+  name of ``home``.  You can therefore have more than one exception
+  view for any given exception in the system: the "most specific" one
+  will be called when the set of request circumstances which match the
+  view registration.  The only predicate that cannot be not be used
+  successfully is ``name``.  The name used to look up an exception
+  view is always the empty string.
+
+  Existing (pre-1.3) normal views registered against objects
+  inheriting from ``Exception`` will continue to work.  Exception
+  views used for user-defined exceptions and system exceptions used as
+  contexts will also work.
+
+  The feature can be used with any view registration mechanism
+  (``@bfg_view`` decorator, ZCML, or imperative ``config.add_view``
+  styles).
+
+  This feature was kindly contributed by Andrey Popp.
+
+- Use "Venusian" (`http://docs.repoze.org/venusian
+  <http://docs.repoze.org/venusian>`_) to perform ``bfg_view``
+  decorator scanning rather than relying on a BFG-internal decorator
+  scanner.  (Truth be told, Venusian is really just a generalization
+  of the BFG-internal decorator scanner).
+
+- Internationalization and localization features as documented in the
+  narrative documentation chapter entitled ``Internationalization and
+  Localization``.
+
+- A new deployment setting named ``default_locale_name`` was added.
+  If this string is present as a Paster ``.ini`` file option, it will
+  be considered the default locale name.  The default locale name is
+  used during locale-related operations such as language translation.
+
+- It is now possible to turn on Chameleon template "debugging mode"
+  for all Chameleon BFG templates by setting a BFG-related Paster
+  ``.ini`` file setting named ``debug_templates``. The exceptions
+  raised by Chameleon templates when a rendering fails are sometimes
+  less than helpful.  ``debug_templates`` allows you to configure your
+  application development environment so that exceptions generated by
+  Chameleon during template compilation and execution will contain
+  more helpful debugging information.  This mode is on by default in
+  all new projects.
+
+- Add a new method of the Configurator named ``derive_view`` which can
+  be used to generate a BFG view callable from a user-supplied
+  function, instance, or class. This useful for external framework and
+  plugin authors wishing to wrap callables supplied by their users
+  which follow the same calling conventions and response conventions
+  as objects that can be supplied directly to BFG as a view callable.
+  See the ``derive_view`` method in the
+  ``repoze.bfg.configuration.Configurator`` docs.
+
+ZCML
+----
+
+- Add a ``translationdir`` ZCML directive to support localization.
+
+- Add a ``localenegotiator`` ZCML directive to support localization.
+
+Deprecations
+------------
+
+-  The exception views feature replaces the need for the
+   ``set_notfound_view`` and ``set_forbidden_view`` methods of the
+   ``Configurator`` as well as the ``notfound`` and ``forbidden`` ZCML
+   directives.  Those methods and directives will continue to work for
+   the foreseeable future, but they are deprecated in the
+   documentation.
+
+Dependencies
+------------
+
+- A new install-time dependency on the ``venusian`` distribution was
+  added.
+
+- A new install-time dependency on the ``translationstring``
+  distribution was added.
+
+- Chameleon 1.2.3 or better is now required (internationalization and
+  per-template debug settings).
+
+Internal
+--------
+
+- View registrations and lookups are now done with three "requires"
+  arguments instead of two to accomodate orthogonality of exception
+  views.
+
+- The ``repoze.bfg.interfaces.IForbiddenView`` and
+  ``repoze.bfg.interfaces.INotFoundView`` interfaces were removed;
+  they weren't APIs and they became vestigial with the addition of
+  exception views.
+
+- Remove ``repoze.bfg.compat.pkgutil_26.py`` and import alias
+  ``repoze.bfg.compat.walk_packages``.  These were only required by
+  internal scanning machinery; Venusian replaced the internal scanning
+  machinery, so these are no longer required.
+
+Documentation
+-------------
+
+- Exception view documentation was added to the ``Hooks`` narrative
+  chapter.
+
+- A new narrative chapter entitled ``Internationalization and
+  Localization`` was added.
+
+- The "Environment Variables and ``ini`` File Settings" chapter was
+  changed: documentation about the ``default_locale_name`` setting was
+  added.
+
+- A new API chapter for the ``repoze.bfg.i18n`` module was added.
+
+- Documentation for the new ``translationdir`` and
+  ``localenegotiator`` ZCML directives were added.
+
+- A section was added to the Templates chapter entitled "Nicer
+  Exceptions in Templates" describing the result of setting
+  ``debug_templates = true``.
+
+Paster Templates
+----------------
+
+- All paster templates now create a ``setup.cfg`` which includes
+  commands related to nose testing and Babel message catalog
+  extraction/compilation.
+
+- A ``default_locale_name = en`` setting was added to each existing paster
+  template.
+
+- A ``debug_templates = true`` setting was added to each existing
+  paster template.
+
+Licensing
+---------
+
+- The Edgewall (BSD) license was added to the LICENSES.txt file, as
+  some code in the ``repoze.bfg.i18n`` derives from Babel source.
+
+1.2 (2010-02-10)
+================
+
+- No changes from 1.2b6.
+
+1.2b6 (2010-02-06)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- Remove magical feature of ``repoze.bfg.url.model_url`` which
+  prepended a fully-expanded urldispatch route URL before a the
+  model's path if it was noticed that the request had matched a route.
+  This feature was ill-conceived, and didn't work in all scenarios.
+
+Bug Fixes
+---------
+
+- More correct conversion of provided ``renderer`` values to resource
+  specification values (internal).
+
+1.2b5 (2010-02-04)
+==================
+
+Bug Fixes
+---------
+
+- 1.2b4 introduced a bug whereby views added via a route configuration
+  that named a view callable and also a ``view_attr`` became broken.
+  Symptom: ``MyViewClass is not callable`` or the ``__call__`` of a
+  class was being called instead of the method named via
+  ``view_attr``.
+
+- Fix a bug whereby a ``renderer`` argument to the ``@bfg_view``
+  decorator that provided a package-relative template filename might
+  not have been resolved properly.  Symptom: inappropriate ``Missing
+  template resource`` errors.
+
+1.2b4 (2010-02-03)
+==================
+
+Documentation
+-------------
+
+- Update GAE tutorial to use Chameleon instead of Jinja2 (now that
+  it's possible).
+
+Bug Fixes
+---------
+
+- Ensure that ``secure`` flag for AuthTktAuthenticationPolicy
+  constructor does what it's documented to do (merge Daniel Holth's
+  fancy-cookies-2 branch).
+
+Features
+--------
+
+- Add ``path`` and ``http_only`` options to
+  AuthTktAuthenticationPolicy constructor (merge Daniel Holth's
+  fancy-cookies-2 branch).
+
+Backwards Incompatibilities
+---------------------------
+
+- Remove ``view_header``, ``view_accept``, ``view_xhr``,
+  ``view_path_info``, ``view_request_method``, ``view_request_param``,
+  and ``view_containment`` predicate arguments from the
+  ``Configurator.add_route`` argument list.  These arguments were
+  speculative.  If you need the features exposed by these arguments,
+  add a view associated with a route using the ``route_name`` argument
+  to the ``add_view`` method instead.
+
+- Remove ``view_header``, ``view_accept``, ``view_xhr``,
+  ``view_path_info``, ``view_request_method``, ``view_request_param``,
+  and ``view_containment`` predicate arguments from the ``route`` ZCML
+  directive attribute set.  These attributes were speculative.  If you
+  need the features exposed by these attributes, add a view associated
+  with a route using the ``route_name`` attribute of the ``view`` ZCML
+  directive instead.
+
+Dependencies
+------------
+
+- Remove dependency on ``sourcecodegen`` (not depended upon by
+  Chameleon 1.1.1+).
+
+1.2b3 (2010-01-24)
+==================
+
+Bug Fixes
+---------
+
+- When "hybrid mode" (both traversal and urldispatch) is in use,
+  default to finding route-related views even if a non-route-related
+  view registration has been made with a more specific context.  The
+  default used to be to find views with a more specific context first.
+  Use the new ``use_global_views`` argument to the route definition to
+  get back the older behavior.
+
+Features
+--------
+
+- Add ``use_global_views`` argument to ``add_route`` method of
+  Configurator.  When this argument is true, views registered for *no*
+  route will be found if no more specific view related to the route is
+  found.
+
+- Add ``use_global_views`` attribute to ZCML ``<route>`` directive
+  (see above).
+
+Internal
+--------
+
+- When registering a view, register the view adapter with the
+  "requires" interfaces as ``(request_type, context_type)`` rather
+  than ``(context_type, request_type)``.  This provides for saner
+  lookup, because the registration will always be made with a specific
+  request interface, but registration may not be made with a specific
+  context interface.  In general, when creating multiadapters, you
+  want to order the requires interfaces so that the elements which
+  are more likely to be registered using specific interfaces are
+  ordered before those which are less likely.
+
+1.2b2 (2010-01-21)
+==================
+
+Bug Fixes
+---------
+
+- When the ``Configurator`` is passed an instance of
+  ``zope.component.registry.Components`` as a ``registry`` constructor
+  argument, fix the instance up to have the attributes we expect of an
+  instance of ``repoze.bfg.registry.Registry`` when ``setup_registry``
+  is called.  This makes it possible to use the global Zope component
+  registry as a BFG application registry.
+
+- When WebOb 0.9.7.1 was used, a deprecation warning was issued for
+  the class attribute named ``charset`` within
+  ``repoze.bfg.request.Request``.  BFG now *requires* WebOb >= 0.9.7,
+  and code was added so that this deprecation warning has disappeared.
+
+- Fix a view lookup ordering bug whereby a view with a larger number
+  of predicates registered first (literally first, not "earlier") for
+  a triad would lose during view lookup to one registered with fewer.
+
+- Make sure views with exactly N custom predicates are always called
+  before views with exactly N non-custom predicates given all else is
+  equal in the view configuration.
+
+Documentation
+-------------
+
+- Change renderings of ZCML directive documentation.
+
+- Add a narrative documentation chapter: "Using the Zope Component
+  Architecture in repoze.bfg".
+
+Dependencies
+------------
+
+- Require WebOb >= 0.9.7
+
+1.2b1 (2010-01-18)
+==================
+
+Bug Fixes
+---------
+
+- In ``bfg_routesalchemy``, ``bfg_alchemy`` paster templates and the
+  ``bfgwiki2`` tutorial, clean up the SQLAlchemy connection by
+  registering a ``repoze.tm.after_end`` callback instead of relying on
+  a ``__del__`` method of a ``Cleanup`` class added to the WSGI
+  environment.  The ``__del__`` strategy was fragile and caused
+  problems in the wild.  Thanks to Daniel Holth for testing.
+
+Features
+--------
+
+- Read logging configuration from PasteDeploy config file ``loggers``
+  section (and related) when ``paster bfgshell`` is invoked.
+
+Documentation
+-------------
+
+- Major rework in preparation for book publication.
+
+1.2a11 (2010-01-05)
+===================
+
+Bug Fixes
+---------
+
+- Make ``paster bfgshell`` and ``paster create -t bfg_xxx`` work on
+  Jython (fix minor incompatibility with treatment of ``__doc__`` at
+  the class level).
+
+- Updated dependency on ``WebOb`` to require a version which supports
+  features now used in tests.
+
+Features
+--------
+
+- Jython compatibility (at least when repoze.bfg.jinja2 is used as the
+  templating engine; Chameleon does not work under Jython).
+
+- Show the derived abspath of template resource specifications in the
+  traceback when a renderer template cannot be found.
+
+- Show the original traceback when a Chameleon template cannot be
+  rendered due to a platform incompatibility.
+
+1.2a10 (2010-01-04)
+===================
+
+Features
+--------
+
+- The ``Configurator.add_view`` method now accepts an argument named
+  ``context``.  This is an alias for the older argument named
+  ``for_``; it is preferred over ``for_``, but ``for_`` will continue
+  to be supported "forever".
+
+- The ``view`` ZCML directive now accepts an attribute named
+  ``context``.  This is an alias for the older attribute named
+  ``for``; it is preferred over ``for``, but ``for`` will continue to
+  be supported "forever".
+
+- The ``Configurator.add_route`` method now accepts an argument named
+  ``view_context``.  This is an alias for the older argument named
+  ``view_for``; it is preferred over ``view_for``, but ``view_for``
+  will continue to be supported "forever".
+
+- The ``route`` ZCML directive now accepts an attribute named
+  ``view_context``.  This is an alias for the older attribute named
+  ``view_for``; it is preferred over ``view_for``, but ``view_for``
+  will continue to be supported "forever".
+
+Documentation and Paster Templates
+----------------------------------
+
+- LaTeX rendering tweaks.
+
+- All uses of the ``Configurator.add_view`` method that used its
+  ``for_`` argument now use the ``context`` argument instead.
+
+- All uses of the ``Configurator.add_route`` method that used its
+  ``view_for`` argument now use the ``view_context`` argument instead.
+
+- All uses of the ``view`` ZCML directive that used its ``for``
+  attribute now use the ``context`` attribute instead.
+
+- All uses of the ``route`` ZCML directive that used its ``view_for``
+  attribute now use the ``view_context`` attribute instead.
+
+- Add a (minimal) tutorial dealing with use of ``repoze.catalog`` in a
+  ``repoze.bfg`` application.
+
+Documentation Licensing
+-----------------------
+
+- Loosen the documentation licensing to allow derivative works: it is
+  now offered under the `Creative Commons
+  Attribution-Noncommercial-Share Alike 3.0 United States License
+  <http://creativecommons.org/licenses/by-nc-sa/3.0/us/>`_.  This is
+  only a documentation licensing change; the ``repoze.bfg`` software
+  continues to be offered under the Repoze Public License at
+  http://repoze.org/license.html (BSD-like).
+
+1.2a9 (2009-12-27)
+==================
+
+Documentation Licensing
+-----------------------
+
+- The *documentation* (the result of ``make <html|latex|htmlhelp>``
+  within the ``docs`` directory) in this release is now offered under
+  the Creative Commons Attribution-Noncommercial-No Derivative Works
+  3.0 United States License as described by
+  http://creativecommons.org/licenses/by-nc-nd/3.0/us/ .  This is only
+  a licensing change for the documentation; the ``repoze.bfg``
+  software continues to be offered under the Repoze Public License
+  at http://repoze.org/license.html (BSD-like).
+
+Documentation
+-------------
+
+- Added manual index entries to generated index.
+
+- Document the previously existing (but non-API)
+  ``repoze.bfg.configuration.Configurator.setup_registry`` method as
+  an official API of a ``Configurator``.
+
+- Fix syntax errors in various documentation code blocks.
+
+- Created new top-level documentation section: "ZCML Directives".
+  This section contains detailed ZCML directive information, some of
+  which was removed from various narrative chapters.
+
+- The LaTeX rendering of the documentation has been improved.
+
+- Added a "Fore-Matter" section with author, copyright, and licensing
+  information.
+
+1.2a8 (2009-12-24)
+==================
+
+Features
+--------
+
+- Add a ``**kw`` arg to the ``Configurator.add_settings`` API.
+
+- Add ``hook_zca`` and ``unhook_zca`` methods to the ``Configurator``
+  API.
+
+- The ``repoze.bfg.testing.setUp`` method now returns a
+  ``Configurator`` instance which can be used to do further
+  configuration during unit tests.
+
+Bug Fixes
+---------
+
+- The ``json`` renderer failed to set the response content type to
+  ``application/json``.  It now does, by setting
+  ``request.response_content_type`` unless this attribute is already
+  set.
+
+- The ``string`` renderer failed to set the response content type to
+  ``text/plain``.  It now does, by setting
+  ``request.response_content_type`` unless this attribute is already
+  set.
+
+Documentation
+-------------
+
+- General documentation improvements by using better Sphinx roles such
+  as "class", "func", "meth", and so on.  This means that there are
+  many more hyperlinks pointing to API documentation for API
+  definitions in all narrative, tutorial, and API documentation
+  elements.
+
+- Added a description of imperative configuration in various places
+  which only described ZCML configuration.
+
+- A syntactical refreshing of various tutorials.
+
+- Added the ``repoze.bfg.authentication``,
+  ``repoze.bfg.authorization``, and ``repoze.bfg.interfaces`` modules
+  to API documentation.
+
+Deprecations
+------------
+
+- The ``repoze.bfg.testing.registerRoutesMapper`` API (added in an
+  early 1.2 alpha) was deprecated.  Its import now generates a
+  deprecation warning.
+
+1.2a7 (2009-12-20)
+==================
+
+Features
+--------
+
+- Add four new testing-related APIs to the
+  ``repoze.bfg.configuration.Configurator`` class:
+  ``testing_securitypolicy``, ``testing_models``,
+  ``testing_add_subscriber``, and ``testing_add_template``.  These
+  were added in order to provide more direct access to the
+  functionality of the ``repoze.bfg.testing`` APIs named
+  ``registerDummySecurityPolicy``, ``registerModels``,
+  ``registerEventListener``, and ``registerTemplateRenderer`` when a
+  configurator is used.  The ``testing`` APIs named are nominally
+  deprecated (although they will likely remain around "forever", as
+  they are in heavy use in the wild).
+
+- Add a new API to the ``repoze.bfg.configuration.Configurator``
+  class: ``add_settings``.  This API can be used to add "settings"
+  (information returned within via the
+  ``repoze.bfg.settings.get_settings`` API) after the configurator has
+  been initially set up.  This is most useful for testing purposes.
+
+- Add a ``custom_predicates`` argument to the ``Configurator``
+  ``add_view`` method, the ``bfg_view`` decorator and the attribute
+  list of the ZCML ``view`` directive.  If ``custom_predicates`` is
+  specified, it must be a sequence of predicate callables (a predicate
+  callable accepts two arguments: ``context`` and ``request`` and
+  returns ``True`` or ``False``).  The associated view callable will
+  only be invoked if all custom predicates return ``True``.  Use one
+  or more custom predicates when no existing predefined predicate is
+  useful.  Predefined and custom predicates can be mixed freely.
+
+- Add a ``custom_predicates`` argument to the ``Configurator``
+  ``add_route`` and the attribute list of the ZCML ``route``
+  directive.  If ``custom_predicates`` is specified, it must be a
+  sequence of predicate callables (a predicate callable accepts two
+  arguments: ``context`` and ``request`` and returns ``True`` or
+  ``False``).  The associated route will match will only be invoked if
+  all custom predicates return ``True``, else route matching
+  continues.  Note that the value ``context`` will always be ``None``
+  when passed to a custom route predicate.  Use one or more custom
+  predicates when no existing predefined predicate is useful.
+  Predefined and custom predicates can be mixed freely.
+
+Internal
+--------
+
+- Remove the ``repoze.bfg.testing.registerTraverser`` function.  This
+  function was never an API.
+
+Documenation
+------------
+
+- Doc-deprecated most helper functions in the ``repoze.bfg.testing``
+  module.  These helper functions likely won't be removed any time
+  soon, nor will they generate a warning any time soon, due to their
+  heavy use in the wild, but equivalent behavior exists in methods of
+  a Configurator.
+
+1.2a6 (2009-12-18)
+==================
+
+Features
+--------
+
+- The ``Configurator`` object now has two new methods: ``begin`` and
+  ``end``.  The ``begin`` method is meant to be called before any
+  "configuration" begins (e.g. before ``add_view``, et. al are
+  called).  The ``end`` method is meant to be called after all
+  "configuration" is complete.
+
+  Previously, before there was imperative configuration at all (1.1
+  and prior), configuration begin and end was invariably implied by
+  the process of loading a ZCML file.  When a ZCML load happened, the
+  threadlocal data structure containing the request and registry was
+  modified before the load, and torn down after the load, making sure
+  that all framework code that needed ``get_current_registry`` for the
+  duration of the ZCML load was satisfied.
+
+  Some API methods called during imperative configuration, (such as
+  ``Configurator.add_view`` when a renderer is involved) end up for
+  historical reasons calling ``get_current_registry``.  However, in
+  1.2a5 and below, the Configurator supplied no functionality that
+  allowed people to make sure that ``get_current_registry`` returned
+  the registry implied by the configurator being used.  ``begin`` now
+  serves this purpose.  Inversely, ``end`` pops the thread local
+  stack, undoing the actions of ``begin``.
+
+  We make this boundary explicit to reduce the potential for confusion
+  when the configurator is used in different circumstances (e.g. in
+  unit tests and app code vs. just in initial app setup).
+
+  Existing code written for 1.2a1-1.2a5 which does not call ``begin``
+  or ``end`` continues to work in the same manner it did before.  It
+  is however suggested that this code be changed to call ``begin`` and
+  ``end`` to reduce the potential for confusion in the future.
+
+- All ``paster`` templates which generate an application skeleton now
+  make use of the new ``begin`` and ``end`` methods of the
+  Configurator they use in their respective copies of ``run.py`` and
+  ``tests.py``.
+
+Documentation
+-------------
+
+- All documentation that makes use of a ``Configurator`` object to do
+  application setup and test setup now makes use of the new ``begin``
+  and ``end`` methods of the configurator.
+
+Bug Fixes
+---------
+
+- When a ``repoze.bfg.exceptions.NotFound`` or
+  ``repoze.bfg.exceptions.Forbidden`` *class* (as opposed to instance)
+  was raised as an exception within a root factory (or route root
+  factory), the exception would not be caught properly by the
+  ``repoze.bfg.`` Router and it would propagate to up the call stack,
+  as opposed to rendering the not found view or the forbidden view as
+  would have been expected.
+
+- When Chameleon page or text templates used as renderers were added
+  imperatively (via ``Configurator.add_view`` or some derivative),
+  they too-eagerly attempted to look up the ``reload_templates``
+  setting via ``get_settings``, meaning they were always registered in
+  non-auto-reload-mode (the default).  Each now waits until its
+  respective ``template`` attribute is accessed to look up the value.
+
+- When a route with the same name as a previously registered route was
+  added, the old route was not removed from the mapper's routelist.
+  Symptom: the old registered route would be used (and possibly
+  matched) during route lookup when it should not have had a chance to
+  ever be used.
+
+1.2a5 (2009-12-10)
+==================
+
+Features
+--------
+
+- When the ``repoze.bfg.exceptions.NotFound`` or
+  ``repoze.bfg.exceptions.Forbidden`` error is raised from within a
+  custom root factory or the ``factory`` of a route, the appropriate
+  response is now sent to the requesting user agent (the result of the
+  notfound view or the forbidden view, respectively).  When these
+  errors are raised from within a root factory, the ``context`` passed
+  to the notfound or forbidden view will be ``None``.  Also, the
+  request will not be decorated with ``view_name``, ``subpath``,
+  ``context``, etc. as would normally be the case if traversal had
+  been allowed to take place.
+
+Internals
+---------
+
+- The exception class representing the error raised by various methods
+  of a ``Configurator`` is now importable as
+  ``repoze.bfg.exceptions.ConfigurationError``.
+
+Documentation
+-------------
+
+- General documentation freshening which takes imperative
+  configuration into account in more places and uses glossary
+  references more liberally.
+
+- Remove explanation of changing the request type in a new request
+  event subscriber, as other predicates are now usually an easier way
+  to get this done.
+
+- Added "Thread Locals" narrative chapter to documentation, and added
+  a API chapter documenting the ``repoze.bfg.threadlocals`` module.
+
+- Added a "Special Exceptions" section to the "Views" narrative
+  documentation chapter explaining the effect of raising
+  ``repoze.bfg.exceptions.NotFound`` and
+  ``repoze.bfg.exceptions.Forbidden`` from within view code.
+
+Dependencies
+------------
+
+- A new dependency on the ``twill`` package was added to the
+  ``setup.py`` ``tests_require`` argument (Twill will only be
+  downloaded when ``repoze.bfg`` ``setup.py test`` or ``setup.py
+  nosetests`` is invoked).
+
+1.2a4 (2009-12-07)
+==================
+
+Features
+--------
+
+- ``repoze.bfg.testing.DummyModel`` now accepts a new constructor
+  keyword argument: ``__provides__``.  If this constructor argument is
+  provided, it should be an interface or a tuple of interfaces.  The
+  resulting model will then provide these interfaces (they will be
+  attached to the constructed model via
+  ``zope.interface.alsoProvides``).
+
+Bug Fixes
+---------
+
+- Operation on GAE was broken, presumably because the
+  ``repoze.bfg.configuration`` module began to attempt to import the
+  ``repoze.bfg.chameleon_zpt`` and ``repoze.bfg.chameleon_text``
+  modules, and these cannot be used on non-CPython platforms.  It now
+  tolerates startup time import failures for these modules, and only
+  raise an import error when a template from one of these packages is
+  actually used.
+
+1.2a3 (2009-12-02)
+==================
+
+Bug Fixes
+---------
+
+- The ``repoze.bfg.url.route_url`` function inappropriately passed
+  along ``_query`` and/or ``_anchor`` arguments to the
+  ``mapper.generate`` function, resulting in blowups.
+
+- When two views were registered with differering ``for`` interfaces
+  or classes, and the ``for`` of first view registered was a
+  superclass of the second, the ``repoze.bfg`` view machinery would
+  incorrectly associate the two views with the same "multiview".
+  Multiviews are meant to be collections of views that have *exactly*
+  the same for/request/viewname values, without taking inheritance
+  into account.  Symptom: wrong view callable found even when you had
+  correctly specified a ``for_`` interface/class during view
+  configuration for one or both view configurations.
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``repoze.bfg.templating`` module has been removed; it had been
+  deprecated in 1.1 and never actually had any APIs in it.
+
+1.2a2 (2009-11-29)
+==================
+
+Bug Fixes
+---------
+
+- The long description of this package (as shown on PyPI) was not
+  valid reStructuredText, and so was not renderable.
+
+- Trying to use an HTTP method name string such as ``GET`` as a
+  ``request_type`` predicate argument caused a startup time failure
+  when it was encountered in imperative configuration or in a
+  decorator (symptom: ``Type Error: Required specification must be a
+  specification``).  This now works again, although ``request_method``
+  is now the preferred predicate argument for associating a view
+  configuration with an HTTP request method.
+
+Documentation
+-------------
+
+- Fixed "Startup" narrative documentation chapter; it was explaining
+  "the old way" an application constructor worked.
+
+1.2a1 (2009-11-28)
+==================
+
+Features
+--------
+
+- An imperative configuration mode.
+
+  A ``repoze.bfg`` application can now begin its life as a single
+  Python file.  Later, the application might evolve into a set of
+  Python files in a package.  Even later, it might start making use of
+  other configuration features, such as ``ZCML``.  But neither the use
+  of a package nor the use of non-imperative configuration is required
+  to create a simple ``repoze.bfg`` application any longer.
+
+  Imperative configuration makes ``repoze.bfg`` competetive with
+  "microframeworks" such as `Bottle <http://bottle.paws.de/>`_ and
+  `Tornado <http://www.tornadoweb.org/>`_.  ``repoze.bfg`` has a good
+  deal of functionality that most microframeworks lack, so this is
+  hopefully a "best of both worlds" feature.
+
+  The simplest possible ``repoze.bfg`` application is now::
+
+     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()
+
+- A new class now exists: ``repoze.bfg.configuration.Configurator``.
+  This class forms the basis for sharing machinery between
+  "imperatively" configured applications and traditional
+  declaratively-configured applications.
+
+- 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 testing
+  registry 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.
+  This will cause the result of the ``zope.component.getSiteManager``
+  function to be the global ZCA registry (the result of
+  ``zope.component.getGlobalSiteManager``) once again.
+
+- The ``run.py`` module in various ``repoze.bfg`` ``paster`` templates
+  now use a ``repoze.bfg.configuration.Configurator`` class instead of
+  the (now-legacy) ``repoze.bfg.router.make_app`` function to produce
+  a WSGI application.
+
+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.
+
+Internals
+---------
+
+- The routes mapper is no longer a root factory wrapper.  It is now
+  consulted directly by the router.
+
+- The ``repoze.bfg.registry.make_registry`` callable has been removed.
+
+- The ``repoze.bfg.view.map_view`` callable has been removed.
+
+- The ``repoze.bfg.view.owrap_view`` callable has been removed.
+
+- The ``repoze.bfg.view.predicate_wrap`` callable has been removed.
+
+- The ``repoze.bfg.view.secure_view`` callable has been removed.
+
+- The ``repoze.bfg.view.authdebug_view`` callable has been removed.
+
+- The ``repoze.bfg.view.renderer_from_name`` callable has been
+  removed.  Use ``repoze.bfg.configuration.Configurator.renderer_from_name``
+  instead (still not an API, however).
+
+- The ``repoze.bfg.view.derive_view`` callable has been removed.  Use
+  ``repoze.bfg.configuration.Configurator.derive_view`` instead (still
+  not an API, however).
+
+- The ``repoze.bfg.settings.get_options`` callable has been removed.
+  Its job has been subsumed by the ``repoze.bfg.settings.Settings``
+  class constructor.
+
+- The ``repoze.bfg.view.requestonly`` function has been moved to
+  ``repoze.bfg.configuration.requestonly``.
+
+- The ``repoze.bfg.view.rendered_response`` function has been moved to
+  ``repoze.bfg.configuration.rendered_response``.
+
+- The ``repoze.bfg.view.decorate_view`` function has been moved to
+  ``repoze.bfg.configuration.decorate_view``.
+
+- The ``repoze.bfg.view.MultiView`` class has been moved to
+  ``repoze.bfg.configuration.MultiView``.
+
+- The ``repoze.bfg.zcml.Uncacheable`` class has been removed.
+
+- The ``repoze.bfg.resource.resource_spec`` function has been removed.
+
+- All ZCML directives which deal with attributes which are paths now
+  use the ``path`` method of the ZCML context to resolve a relative
+  name to an absolute one (imperative configuration requirement).
+
+- The ``repoze.bfg.scripting.get_root`` API now uses a 'real' WebOb
+  request rather than a FakeRequest when it sets up the request as a
+  threadlocal.
+
+- The ``repoze.bfg.traversal.traverse`` API now uses a 'real' WebOb
+  request rather than a FakeRequest when it calls the traverser.
+
+- The ``repoze.bfg.request.FakeRequest`` class has been removed.
+
+- Most uses of the ZCA threadlocal API (the ``getSiteManager``,
+  ``getUtility``, ``getAdapter``, ``getMultiAdapter`` threadlocal API)
+  have been removed from the core.  Instead, when a threadlocal is
+  necessary, the core uses the
+  ``repoze.bfg.threadlocal.get_current_registry`` API to obtain the
+  registry.
+
+- The internal ILogger utility named ``repoze.bfg.debug`` is now just
+  an IDebugLogger unnamed utility.  A named utility with the old name
+  is registered for b/w compat.
+
+- The ``repoze.bfg.interfaces.ITemplateRendererFactory`` interface was
+  removed; it has become unused.
+
+- Instead of depending on the ``martian`` package to do code scanning,
+  we now just use our own scanning routines.
+
+- We now no longer have a dependency on ``repoze.zcml`` package;
+  instead, the ``repoze.bfg`` package includes implementations of the
+  ``adapter``, ``subscriber`` and ``utility`` directives.
+
+- Relating to the following functions:
+
+  ``repoze.bfg.view.render_view``
+
+  ``repoze.bfg.view.render_view_to_iterable``
+
+  ``repoze.bfg.view.render_view_to_response``
+
+  ``repoze.bfg.view.append_slash_notfound_view``
+
+  ``repoze.bfg.view.default_notfound_view``
+
+  ``repoze.bfg.view.default_forbidden_view``
+
+  ``repoze.bfg.configuration.rendered_response``
+
+  ``repoze.bfg.security.has_permission``
+
+  ``repoze.bfg.security.authenticated_userid``
+
+  ``repoze.bfg.security.effective_principals``
+
+  ``repoze.bfg.security.view_execution_permitted``
+
+  ``repoze.bfg.security.remember``
+
+  ``repoze.bfg.security.forget``
+
+  ``repoze.bfg.url.route_url``
+
+  ``repoze.bfg.url.model_url``
+
+  ``repoze.bfg.url.static_url``
+
+  ``repoze.bfg.traversal.virtual_root``
+
+  Each of these functions now expects to be called with a request
+  object that has a ``registry`` attribute which represents the
+  current ``repoze.bfg`` registry.  They fall back to obtaining the
+  registry from the threadlocal API.
+
+Backwards Incompatibilites
+--------------------------
+
+- Unit tests which use ``zope.testing.cleanup.cleanUp`` for the
+  purpose of isolating tests from one another may now begin to fail
+  due to lack of isolation between tests.
+
+  Here's why: In repoze.bfg 1.1 and prior, the registry returned by
+  ``repoze.bfg.threadlocal.get_current_registry`` when no other
+  registry had been pushed on to the threadlocal stack was the
+  ``zope.component.globalregistry.base`` global registry (aka the
+  result of ``zope.component.getGlobalSiteManager()``).  In repoze.bfg
+  1.2+, however, the registry returned in this situation is the new
+  module-scope ``repoze.bfg.registry.global_registry`` object.  The
+  ``zope.testing.cleanup.cleanUp`` function clears the
+  ``zope.component.globalregistry.base`` global registry
+  unconditionally.  However, it does not know about the
+  ``repoze.bfg.registry.global_registry`` object, so it does not clear
+  it.
+
+  If you use the ``zope.testing.cleanup.cleanUp`` function in the
+  ``setUp`` of test cases in your unit test suite instead of using the
+  (more correct as of 1.1) ``repoze.bfg.testing.setUp``, you will need
+  to replace all calls to ``zope.testing.cleanup.cleanUp`` with a call
+  to ``repoze.bfg.testing.setUp``.
+
+  If replacing all calls to ``zope.testing.cleanup.cleanUp`` with a
+  call to ``repoze.bfg.testing.setUp`` is infeasible, you can put this
+  bit of code somewhere that is executed exactly **once** (*not* for
+  each test in a test suite; in the `` __init__.py`` of your package
+  or your package's ``tests`` subpackage would be a reasonable
+  place)::
+
+    import zope.testing.cleanup
+    from repoze.bfg.testing import setUp
+    zope.testing.cleanup.addCleanUp(setUp)
+
+- When there is no "current registry" in the
+  ``repoze.bfg.threadlocal.manager`` threadlocal data structure (this
+  is the case when there is no "current request" or we're not in the
+  midst of a ``r.b.testing.setUp``-bounded unit test), the ``.get``
+  method of the manager returns a data structure containing a *global*
+  registry.  In previous releases, this function returned the global
+  Zope "base" registry: the result of
+  ``zope.component.getGlobalSiteManager``, which is an instance of the
+  ``zope.component.registry.Component`` class.  In this release,
+  however, the global registry returns a globally importable instance
+  of the ``repoze.bfg.registry.Registry`` class.  This registry
+  instance can always be imported as
+  ``repoze.bfg.registry.global_registry``.
+
+  Effectively, this means that when you call
+  ``repoze.bfg.threadlocal.get_current_registry`` when no request or
+  ``setUp`` bounded unit test is in effect, you will always get back
+  the global registry that lives in
+  ``repoze.bfg.registry.global_registry``.  It also means that
+  ``repoze.bfg`` APIs that *call* ``get_current_registry`` will use
+  this registry.
+
+  This change was made because ``repoze.bfg`` now expects the registry
+  it uses to have a slightly different API than a bare instance of
+  ``zope.component.registry.Components``.
+
+- 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).
+
+1.1.1 (2009-11-21)
+==================
+
+Bug Fixes
+---------
+
+- "Hybrid mode" applications (applications which explicitly used
+  traversal *after* url dispatch via ``<route>`` paths containing the
+  ``*traverse`` element) were broken in 1.1-final and all 1.1 alpha
+  and beta releases.  Views registered without a ``route_name`` route
+  shadowed views registered with a ``route_name`` inappropriately.
+
+1.1 (2009-11-15)
+================
+
+Internals
+---------
+
+- Remove dead IRouteRequirement interface from ``repoze.bfg.zcml``
+  module.
+
+Documentation
+-------------
+
+- Improve the "Extending an Existing Application" narrative chapter.
+
+- Add more sections to the "Defending Design" chapter.
+
+1.1b4 (2009-11-12)
+==================
+
+Bug Fixes
+---------
+
+- Use ``alsoProvides`` in the urldispatch module to attach an
+  interface to the request rather than ``directlyProvides`` to avoid
+  disturbing interfaces set in a NewRequest event handler.
+
+Documentation
+-------------
+
+- Move 1.0.1 and previous changelog to HISTORY.txt.
+
+- Add examples to ``repoze.bfg.url.model_url`` docstring.
+
+- Add "Defending BFG Design" chapter to frontpage docs.
+
+Templates
+---------
+
+- Remove ``ez_setup.py`` and its import from all paster templates,
+  samples, and tutorials for ``distribute`` compatibility.  The
+  documentation already explains how to install virtualenv (which will
+  include some ``setuptools`` package), so these files, imports and
+  usages were superfluous.
+
+Deprecations
+------------
+
+- The ``options`` kw arg to the ``repoze.bfg.router.make_app``
+  function is deprecated.  In its place is the keyword argument
+  ``settings``.  The ``options`` keyword continues to work, and a
+  deprecation warning is not emitted when it is detected.  However,
+  the paster templates, code samples, and documentation now make
+  reference to ``settings`` rather than ``options``.  This
+  change/deprecation was mainly made for purposes of clarity and
+  symmetry with the ``get_settings()`` API and dicussions of
+  "settings" in various places in the docs: we want to use the same
+  name to refer to the same thing everywhere.
+
+1.1b3 (2009-11-06)
+==================
+
+Features
+--------
+
+- ``repoze.bfg.testing.registerRoutesMapper`` testing facility added.
+  This testing function registers a routes "mapper" object in the
+  registry, for tests which require its presence.  This function is
+  documented in the ``repoze.bfg.testing`` API documentation.
+
+Bug Fixes
+---------
+
+- Compound statements that used an assignment entered into in an
+  interactive IPython session invoked via ``paster bfgshell`` no
+  longer fail to mutate the shell namespace correctly.  For example,
+  this set of statements used to fail::
+
+    In [2]: def bar(x): return x
+      ...:
+    In [3]: list(bar(x) for x in 'abc')
+    Out[3]: NameError: 'bar'
+
+  In this release, the ``bar`` function is found and the correct
+  output is now sent to the console.  Thanks to Daniel Holth for the
+  patch.
+
+- The ``bfgshell`` command did not function properly; it was still
+  expecting to be able to call the root factory with a bare
+  ``environ`` rather than a request object.
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``repoze.bfg.scripting.get_root`` function now expects a
+  ``request`` object as its second argument rather than an
+  ``environ``.
+
+1.1b2 (2009-11-02)
+==================
+
+Bug Fixes
+---------
+
+- Prevent PyPI installation failure due to ``easy_install`` trying way
+  too hard to guess the best version of Paste.  When ``easy_install``
+  pulls from PyPI it reads links off various pages to determine "more
+  up to date" versions. It incorrectly picks up a link for an ancient
+  version of a package named "Paste-Deploy-0.1" (note the dash) when
+  trying to find the "Paste" distribution and somehow believes it's
+  the latest version of "Paste".  It also somehow "helpfully" decides
+  to check out a version of this package from SVN.  We pin the Paste
+  dependency version to a version greater than 1.7 to work around
+  this ``easy_install`` bug.
+
+Documentation
+-------------
+
+- Fix "Hybrid" narrative chapter: stop claiming that ``<view>``
+  statements that mention a route_name need to come afer (in XML
+  order) the ``<route>`` statement which creates the route.  This
+  hasn't been true since 1.1a1.
+
+- "What's New in ``repoze.bfg`` 1.1" document added to narrative
+  documentation.
+
+Features
+--------
+
+- Add a new event type: ``repoze.bfg.events.AfterTraversal``.  Events
+  of this type will be sent after traversal is completed, but before
+  any view code is invoked.  Like ``repoze.bfg.events.NewRequest``,
+  This event will have a single attribute: ``request`` representing
+  the current request.  Unlike the request attribute of
+  ``repoze.bfg.events.NewRequest`` however, during an AfterTraversal
+  event, the request object will possess attributes set by the
+  traverser, most notably ``context``, which will be the context used
+  when a view is found and invoked.  The interface
+  ``repoze.bfg.events.IAfterTraversal`` can be used to subscribe to
+  the event.  For example::
+
+    <subscriber for="repoze.bfg.interfaces.IAfterTraversal"
+                handler="my.app.handle_after_traverse"/>
+
+  Like any framework event, a subscriber function should expect one
+  parameter: ``event``.
+
+Dependencies
+------------
+
+- Rather than depending on ``chameleon.core`` and ``chameleon.zpt``
+  distributions individually, depend on Malthe's repackaged
+  ``Chameleon`` distribution (which includes both ``chameleon.core``
+  and ``chameleon.zpt``).
+
+1.1b1 (2009-11-01)
+==================
+
+Bug Fixes
+---------
+
+- The routes root factory called route factories and the default route
+  factory with an environ rather than a request.  One of the symptoms
+  of this bug: applications generated using the ``bfg_zodb`` paster
+  template in 1.1a9 did not work properly.
+
+- Reinstate ``renderer`` alias for ``view_renderer`` in the
+  ``<route>`` ZCML directive (in-the-wild 1.1a bw compat).
+
+- ``bfg_routesalchemy`` paster template: change ``<route>``
+  declarations: rename ``renderer`` attribute to ``view_renderer``.
+
+- Header values returned by the ``authtktauthenticationpolicy``
+  ``remember`` and ``forget`` methods would be of type ``unicode``.
+  This violated the WSGI spec, causing a ``TypeError`` to be raised
+  when these headers were used under ``mod_wsgi``.
+
+- If a BFG app that had a route matching the root URL was mounted
+  under a path in modwsgi, ala ``WSGIScriptAlias /myapp
+  /Users/chrism/projects/modwsgi/env/bfg.wsgi``, the home route (a
+  route with the path of ``'/'`` or ``''``) would not match when the
+  path ``/myapp`` was visited (only when the path ``/myapp/`` was
+  visited).  This is now fixed: if the urldispatch root factory notes
+  that the PATH_INFO is empty, it converts it to a single slash before
+  trying to do matching.
+
+Documentation
+-------------
+
+- In ``<route>`` declarations in tutorial ZCML, rename ``renderer``
+  attribute to ``view_renderer`` (fwd compat).
+
+- Fix various tutorials broken by 1.1a9 ``<route>`` directive changes.
+
+Internal
+--------
+
+- Deal with a potential circref in the traversal module.
+
+1.1a9 (2009-10-31)
+==================
+
+Bug Fixes
+---------
+
+- An incorrect ZCML conflict would be encountered when the
+  ``request_param`` predicate attribute was used on the ZCML ``view``
+  directive if any two otherwise same-predicated views had the
+  combination of a predicate value with an ``=`` sign and one without
+  (e.g. ``a`` vs. ``a=123``).
+
+Features
+--------
+
+- In previous versions of BFG, the "root factory" (the ``get_root``
+  callable passed to ``make_app`` or a function pointed to by the
+  ``factory`` attribute of a route) was called with a "bare" WSGI
+  environment.  In this version, and going forward, it will be called
+  with a ``request`` object.  The request object passed to the factory
+  implements dictionary-like methods in such a way that existing root
+  factory code which expects to be passed an environ will continue to
+  work.
+
+- The ``__call__`` of a plugin "traverser" implementation (registered
+  as an adapter for ``ITraverser`` or ``ITraverserFactory``) will now
+  receive a *request* as the single argument to its ``__call__``
+  method.  In previous versions it was passed a WSGI ``environ``
+  object.  The request object passed to the factory implements
+  dictionary-like methods in such a way that existing traverser code
+  which expects to be passed an environ will continue to work.
+
+- The ZCML ``route`` directive's attributes ``xhr``,
+  ``request_method``, ``path_info``, ``request_param``, ``header`` and
+  ``accept`` are now *route* predicates rather than *view* predicates.
+  If one or more of these predicates is specified in the route
+  configuration, all of the predicates must return true for the route
+  to match a request.  If one or more of the route predicates
+  associated with a route returns ``False`` when checked during a
+  request, the route match fails, and the next match in the routelist
+  is tried.  This differs from the previous behavior, where no route
+  predicates existed and all predicates were considered view
+  predicates, because in that scenario, the next route was not tried.
+
+Documentation
+-------------
+
+- Various changes were made to narrative and API documentation
+  supporting the change from passing a request rather than an environ
+  to root factories and traversers.
+
+Internal
+--------
+
+- The request implements dictionary-like methods that mutate and query
+  the WSGI environ.  This is only for the purpose of backwards
+  compatibility with root factories which expect an ``environ`` rather
+  than a request.
+
+- The ``repoze.bfg.request.create_route_request_factory`` function,
+  which returned a request factory was removed in favor of a
+  ``repoze.bfg.request.route_request_interface`` function, which
+  returns an interface.
+
+- The ``repoze.bfg.request.Request`` class, which is a subclass of
+  ``webob.Request`` now defines its own ``__setattr__``,
+  ``__getattr__`` and ``__delattr__`` methods, which override the
+  default WebOb behavior.  The default WebOb behavior stores
+  attributes of the request in ``self.environ['webob.adhoc_attrs']``,
+  and retrieves them from that dictionary during a ``__getattr__``.
+  This behavior was undesirable for speed and "expectation" reasons.
+  Now attributes of the ``request`` are stored in ``request.__dict__``
+  (as you otherwise might expect from an object that did not override
+  these methods).
+
+- The router no longer calls ``repoze.bfg.traversal._traverse`` and
+  does its work "inline" (speed).
+
+- Reverse the order in which the router calls the request factory and
+  the root factory.  The request factory is now called first; the
+  resulting request is passed to the root factory.
+
+- The ``repoze.bfg.request.request_factory`` function has been
+  removed.  Its functionality is no longer required.
+
+- The "routes root factory" that wraps the default root factory when
+  there are routes mentioned in the configuration now attaches an
+  interface to the request via ``zope.interface.directlyProvides``.
+  This replaces logic in the (now-gone)
+  ``repoze.bfg.request.request_factory`` function.
+
+- The ``route`` and ``view`` ZCML directives now register an interface
+  as a named utility (retrieved from
+  ``repoze.bfg.request.route_request_interface``) rather than a
+  request factory (the previous return value of the now-missing 
+  ``repoze.bfg.request.create_route_request_factory``.
+
+- The ``repoze.bfg.functional`` module was renamed to
+  ``repoze.bfg.compat``.
+
+Backwards Incompatibilities
+---------------------------
+
+- Explicitly revert the feature introduced in 1.1a8: where the name
+  ``root`` is available as an attribute of the request before a
+  NewRequest event is emitted.  This makes some potential future
+  features impossible, or at least awkward (such as grouping traversal
+  and view lookup into a single adapter lookup).
+
+- The ``containment``, ``attr`` and ``renderer`` attributes of the
+  ``route`` ZCML directive were removed.
+
+1.1a8 (2009-10-27)
+==================
+
+Features
+--------
+
+- Add ``path_info`` view configuration predicate.
+
+- ``paster bfgshell`` now supports IPython if it's available for
+  import.  Thanks to Daniel Holth for the initial patch.
+
+- Add ``repoze.bfg.testing.registerSettings`` API, which is documented
+  in the "repoze.bfg.testing" API chapter.  This allows for
+  registration of "settings" values obtained via
+  ``repoze.bfg.settings.get_settings()`` for use in unit tests.
+
+- The name ``root`` is available as an attribute of the request
+  slightly earlier now (before a NewRequest event is emitted).
+  ``root`` is the result of the application "root factory".
+
+- Added ``max_age`` parameter to ``authtktauthenticationpolicy`` ZCML
+  directive.  If this value is set, it must be an integer representing
+  the number of seconds which the auth tkt cookie will survive.
+  Mainly, its existence allows the auth_tkt cookie to survive across
+  browser sessions.
+
+Bug Fixes
+---------
+
+- Fix bug encountered during "scan" (when ``<scan ..>`` directive is
+  used in ZCML) introduced in 1.1a7.  Symptom: ``AttributeError:
+  object has no attribute __provides__`` raised at startup time.
+
+- The ``reissue_time`` argument to the ``authtktauthenticationpolicy``
+  ZCML directive now actually works.  When it is set to an integer
+  value, an authticket set-cookie header is appended to the response
+  whenever a request requires authentication and 'now' minus the
+  authticket's timestamp is greater than ``reissue_time`` seconds.
+
+Documentation
+-------------
+
+- Add a chapter titled "Request and Response" to the narrative
+  documentation, content cribbed from the WebOb documentation.
+
+- Call out predicate attributes of ZCML directive within "Views"
+  chapter.
+
+- Fix route_url documentation (``_query`` argument documented as
+  ``query`` and ``_anchor`` argument documented as ``anchor``).
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``authtkt`` authentication policy ``remember`` method now no
+  longer honors ``token`` or ``userdata`` keyword arguments.
+
+Internal
+--------
+
+- Change how ``bfg_view`` decorator works when used as a class method
+  decorator.  In 1.1a7, the``scan``directive actually tried to grope
+  every class in scanned package at startup time, calling ``dir``
+  against each found class, and subsequently invoking ``getattr``
+  against each thing found by ``dir`` to see if it was a method.  This
+  led to some strange symptoms (e.g. ``AttributeError: object has no
+  attribute __provides__``), and was generally just a bad idea.  Now,
+  instead of groping classes for methods at startup time, we just
+  cause the ``bfg_view`` decorator itself to populate the method's
+  class' ``__dict__`` when it is used as a method decorator.  This
+  also requires a nasty _getframe thing but it's slightly less nasty
+  than the startup time groping behavior.  This is essentially a
+  reversion back to 1.1a6 "grokking" behavior plus some special magic
+  for using the ``bfg_view`` decorator as method decorator inside the
+  ``bfg_view`` class itself.
+
+- The router now checks for a ``global_response_headers`` attribute of
+  the request object before returning a response.  If this value
+  exists, it is presumed to be a sequence of two-tuples, representing
+  a set of headers to append to the 'normal' response headers.  This
+  feature is internal, rather than exposed externally, because it's
+  unclear whether it will stay around in the long term.  It was added
+  to support the ``reissue_time`` feature of the authtkt
+  authentication policy.
+
+- The interface ITraverserFactory is now just an alias for ITraverser.
+
+1.1a7 (2009-10-18)
+==================
+
+Features
+--------
+
+- More than one ``@bfg_view`` decorator may now be stacked on top of
+  any number of others.  Each invocation of the decorator registers a
+  single view configuration.  For instance, the following combination
+  of decorators and a function will register two view configurations
+  for the same view callable::
+
+    from repoze.bfg.view import bfg_view
+
+    @bfg_view(name='edit')
+    @bfg_view(name='change')
+    def edit(context, request):
+        pass
+
+  This makes it possible to associate more than one view configuration
+  with a single callable without requiring any ZCML.
+
+- The ``@bfg_view`` decorator can now be used against a class method::
+
+    from webob import Response
+    from repoze.bfg.view import bfg_view
+
+    class MyView(object):
+        def __init__(self, context, request):
+            self.context = context
+            self.request = request
+
+        @bfg_view(name='hello')
+        def amethod(self):
+            return Response('hello from %s!' % self.context)
+
+  When the bfg_view decorator is used against a class method, a view
+  is registered for the *class* (it's a "class view" where the "attr"
+  happens to be the name of the method it is attached to), so the
+  class it's defined within must have a suitable constructor: one that
+  accepts ``context, request`` or just ``request``.
+
+Documentation
+-------------
+
+- Added ``Changing the Traverser`` and ``Changing How
+  :mod:`repoze.bfg.url.model_url` Generates a URL`` to the "Hooks"
+  narrative chapter of the docs.
+
+Internal
+--------
+
+- Remove ``ez_setup.py`` and imports of it within ``setup.py``.  In
+  the new world, and as per virtualenv setup instructions, people will
+  already have either setuptools or distribute.
+
+1.1a6 (2009-10-15)
+==================
+
+Features
+--------
+
+- Add ``xhr``, ``accept``, and ``header`` view configuration
+  predicates to ZCML view declaration, ZCML route declaration, and
+  ``bfg_view`` decorator.  See the ``Views`` narrative documentation
+  chapter for more information about these predicates.
+
+- Add ``setUp`` and ``tearDown`` functions to the
+  ``repoze.bfg.testing`` module.  Using ``setUp`` in a test setup and
+  ``tearDown`` in a test teardown is now the recommended way to do
+  component registry setup and teardown.  Previously, it was
+  recommended that a single function named
+  ``repoze.bfg.testing.cleanUp`` be called in both the test setup and
+  tear down.  ``repoze.bfg.testing.cleanUp`` still exists (and will
+  exist "forever" due to its widespread use); it is now just an alias
+  for ``repoze.bfg.testing.setUp`` and is nominally deprecated.
+
+- The BFG component registry is now available in view and event
+  subscriber code as an attribute of the request
+  ie. ``request.registry``.  This fact is currently undocumented
+  except for this note, because BFG developers never need to interact
+  with the registry directly anywhere else.
+
+- The BFG component registry now inherits from ``dict``, meaning that
+  it can optionally be used as a simple dictionary.  *Component*
+  registrations performed against it via e.g. ``registerUtility``,
+  ``registerAdapter``, and similar API methods are kept in a
+  completely separate namespace than its dict members, so using the
+  its component API methods won't effect the keys and values in the
+  dictionary namespace.  Likewise, though the component registry
+  "happens to be" a dictionary, use of mutating dictionary methods
+  such as ``__setitem__`` will have no influence on any component
+  registrations made against it.  In other words, the registry object
+  you obtain via e.g. ``repoze.bfg.threadlocal.get_current_registry``
+  or ``request.registry`` happens to be both a component registry and
+  a dictionary, but using its component-registry API won't impact data
+  added to it via its dictionary API and vice versa.  This is a
+  forward compatibility move based on the goals of "marco".
+
+- Expose and document ``repoze.bfg.testing.zcml_configure`` API.  This
+  function populates a component registry from a ZCML file for testing
+  purposes.  It is documented in the "Unit and Integration Testing"
+  chapter.
+
+Documentation
+-------------
+
+- Virtual hosting narrative docs chapter updated with info about
+  ``mod_wsgi``.
+
+- Point all index URLs at the literal 1.1 index (this alpha cycle may
+  go on a while).
+
+- Various tutorial test modules updated to use
+  ``repoze.bfg.testing.setUp`` and ``repoze.bfg.testing.tearDown``
+  methods in order to encourage this as best practice going forward.
+
+- Added "Creating Integration Tests" section to unit testing narrative
+  documentation chapter.  As a result, the name of the unittesting
+  chapter is now "Unit and Integration Testing".
+
+Backwards Incompatibilities
+---------------------------
+
+- Importing ``getSiteManager`` and ``get_registry`` from
+  ``repoze.bfg.registry`` is no longer supported.  These imports were
+  deprecated in repoze.bfg 1.0.  Import of ``getSiteManager`` should
+  be done as ``from zope.component import getSiteManager``.  Import of
+  ``get_registry`` should be done as ``from repoze.bfg.threadlocal
+  import get_current_registry``.  This was done to prevent a circular
+  import dependency.
+
+- Code bases which alternately invoke both
+  ``zope.testing.cleanup.cleanUp`` and ``repoze.bfg.testing.cleanUp``
+  (treating them equivalently, using them interchangeably) in the
+  setUp/tearDown of unit tests will begin to experience test failures
+  due to lack of test isolation.  The "right" mechanism is
+  ``repoze.bfg.testing.cleanUp`` (or the combination of
+  ``repoze.bfg.testing.setUp`` and
+  ``repoze.bfg.testing.tearDown``). but a good number of legacy
+  codebases will use ``zope.testing.cleanup.cleanUp`` instead.  We
+  support ``zope.testing.cleanup.cleanUp`` but not in combination with
+  ``repoze.bfg.testing.cleanUp`` in the same codebase.  You should use
+  one or the other test cleanup function in a single codebase, but not
+  both.
+
+Internal
+--------
+
+- Created new ``repoze.bfg.configuration`` module which assumes
+  responsibilities previously held by the ``repoze.bfg.registry`` and
+  ``repoze.bfg.router`` modules (avoid a circular import dependency).
+
+- The result of the ``zope.component.getSiteManager`` function in unit
+  tests set up with ``repoze.bfg.testing.cleanUp`` or
+  ``repoze.bfg.testing.setUp`` will be an instance of
+  ``repoze.bfg.registry.Registry`` instead of the global
+  ``zope.component.globalregistry.base`` registry.  This also means
+  that the threadlocal ZCA API functions such as ``getAdapter`` and
+  ``getUtility`` as well as internal BFG machinery (such as
+  ``model_url`` and ``route_url``) will consult this registry within
+  unit tests. This is a forward compatibility move based on the goals
+  of "marco".
+
+- Removed ``repoze.bfg.testing.addCleanUp`` function and associated
+  module-scope globals.  This was never an API.
+
+1.1a5 (2009-10-10)
+==================
+
+Documentation
+-------------
+
+- Change "Traversal + ZODB" and "URL Dispatch + SQLAlchemy" Wiki
+  tutorials to make use of the new-to-1.1 "renderer" feature (return
+  dictionaries from all views).
+
+- Add tests to the "URL Dispatch + SQLAlchemy" tutorial after the
+  "view" step.
+
+- Added a diagram of model graph traversal to the "Traversal"
+  narrative chapter of the documentation.
+
+- An ``exceptions`` API chapter was added, documenting the new
+  ``repoze.bfg.exceptions`` module.
+
+- Describe "request-only" view calling conventions inside the
+  urldispatch narrative chapter, where it's most helpful.
+
+- Add a diagram which explains the operation of the BFG router to the
+  "Router" narrative chapter.
+
+Features
+--------
+
+- Add a new ``repoze.bfg.testing`` API: ``registerRoute``, for
+  registering routes to satisfy calls to
+  e.g. ``repoze.bfg.url.route_url`` in unit tests.
+
+- The ``notfound`` and ``forbidden`` ZCML directives now accept the
+  following addtional attributes: ``attr``, ``renderer``, and
+  ``wrapper``.  These have the same meaning as they do in the context
+  of a ZCML ``view`` directive.
+
+- For behavior like Django's ``APPEND_SLASH=True``, use the
+  ``repoze.bfg.view.append_slash_notfound_view`` view as the Not Found
+  view in your application.  When this view is the Not Found view
+  (indicating that no view was found), and any routes have been
+  defined in the configuration of your application, if the value of
+  ``PATH_INFO`` does not already end in a slash, and if the value of
+  ``PATH_INFO`` *plus* a slash matches any route's path, do an HTTP
+  redirect to the slash-appended PATH_INFO.  Note that this will
+  *lose* ``POST`` data information (turning it into a GET), so you
+  shouldn't rely on this to redirect POST requests.
+
+- Speed up ``repoze.bfg.location.lineage`` slightly.
+
+- Speed up ``repoze.bfg.encode.urlencode`` (nee'
+  ``repoze.bfg.url.urlencode``) slightly.
+
+- Speed up ``repoze.bfg.traversal.model_path``.
+
+- Speed up ``repoze.bfg.traversal.model_path_tuple`` slightly.
+
+- Speed up ``repoze.bfg.traversal.traverse`` slightly.
+
+- Speed up ``repoze.bfg.url.model_url`` slightly.
+
+- Speed up ``repoze.bfg.url.route_url`` slightly.
+
+- Sped up ``repoze.bfg.traversal.ModelGraphTraverser:__call__``
+  slightly.
+
+- Minor speedup of ``repoze.bfg.router.Router.__call__``.
+
+- New ``repoze.bfg.exceptions`` module was created to house exceptions
+  that were previously sprinkled through various modules.
+
+Internal
+--------
+
+- Move ``repoze.bfg.traversal._url_quote`` into ``repoze.bfg.encode``
+  as ``url_quote``.
+
+Deprecations
+------------
+
+- The import of ``repoze.bfg.view.NotFound`` is deprecated in favor of
+  ``repoze.bfg.exceptions.NotFound``.  The old location still
+  functions, but emits a deprecation warning.
+
+- The import of ``repoze.bfg.security.Unauthorized`` is deprecated in
+  favor of ``repoze.bfg.exceptions.Forbidden``.  The old location
+  still functions but emits a deprecation warning.  The rename from
+  ``Unauthorized`` to ``Forbidden`` brings parity to the name of
+  the exception and the system view it invokes when raised.
+
+Backwards Incompatibilities
+---------------------------
+
+- We previously had a Unicode-aware wrapper for the
+  ``urllib.urlencode`` function named ``repoze.bfg.url.urlencode``
+  which delegated to the stdlib function, but which marshalled all
+  unicode values to utf-8 strings before calling the stdlib version.
+  A newer replacement now lives in ``repoze.bfg.encode`` The
+  replacement does not delegate to the stdlib.
+
+  The replacement diverges from the stdlib implementation and the
+  previous ``repoze.bfg.url`` url implementation inasmuch as its
+  ``doseq`` argument is now a decoy: it always behaves in the
+  ``doseq=True`` way (which is the only sane behavior) for speed
+  purposes.
+
+  The old import location (``repoze.bfg.url.urlencode``) still
+  functions and has not been deprecated.
+
+- In 0.8a7, the return value expected from an object implementing
+  ``ITraverserFactory`` was changed from a sequence of values to a
+  dictionary containing the keys ``context``, ``view_name``,
+  ``subpath``, ``traversed``, ``virtual_root``, ``virtual_root_path``,
+  and ``root``.  Until now, old-style traversers which returned a
+  sequence have continued to work but have generated a deprecation
+  warning.  In this release, traversers which return a sequence
+  instead of a dictionary will no longer work.
+
+1.1a4 (2009-09-23)
+==================
+
+Bug Fixes
+---------
+
+- On 64-bit Linux systems, views that were members of a multiview
+  (orderings of views with predicates) were not evaluated in the
+  proper order.  Symptom: in a configuration that had two views with
+  the same name but one with a ``request_method=POST`` predicate and
+  one without, the one without the predicate would be called
+  unconditionally (even if the request was a POST request).  Thanks
+  much to Sebastien Douche for providing the buildbots that pointed
+  this out.
+
+Documentation
+-------------
+
+- Added a tutorial which explains how to use ``repoze.session``
+  (ZODB-based sessions) in a ZODB-based repoze.bfg app.
+
+- Added a tutorial which explains how to add ZEO to a ZODB-based
+  ``repoze.bfg`` application.
+
+- Added a tutorial which explains how to run a ``repoze.bfg``
+  application under `mod_wsgi <http://code.google.com/p/modwsgi/>`_.
+  See "Running a repoze.bfg Application under mod_wsgi" in the
+  tutorials section of the documentation.
+
+Features
+--------
+
+- Add a ``repoze.bfg.url.static_url`` API which is capable of
+  generating URLs to static resources defined by the ``<static>`` ZCML
+  directive.  See the "Views" narrative chapter's section titled
+  "Generating Static Resource URLs" for more information.
+
+- Add a ``string`` renderer.  This renderer converts a non-Response
+  return value of any view callble into a string.  It is documented in
+  the "Views" narrative chapter.
+
+- Give the ``route`` ZCML directive the ``view_attr`` and
+  ``view_renderer`` parameters (bring up to speed with 1.1a3
+  features).  These can also be spelled as ``attr`` and ``renderer``.
+
+Backwards Incompatibilities
+---------------------------
+
+- An object implementing the ``IRenderer`` interface (and
+  ``ITemplateRenderer`, which is a subclass of ``IRenderer``) must now
+  accept an extra ``system`` argument in its ``__call__`` method
+  implementation.  Values computed by the system (as opposed to by the
+  view) are passed by the system in the ``system`` parameter, which
+  will always be a dictionary.  Keys in the dictionary include:
+  ``view`` (the view object that returned the value),
+  ``renderer_name`` (the template name or simple name of the
+  renderer), ``context`` (the context object passed to the view), and
+  ``request`` (the request object passed to the view).  Previously
+  only ITemplateRenderers received system arguments as elements inside
+  the main ``value`` dictionary.
+
+Internal
+--------
+
+- The way ``bfg_view`` declarations are scanned for has been modified.
+  This should have no external effects.
+
+- Speed: do not register an ITraverserFactory in configure.zcml;
+  instead rely on queryAdapter and a manual default to
+  ModelGraphTraverser.
+
+- Speed: do not register an IContextURL in configure.zcml; instead
+  rely on queryAdapter and a manual default to TraversalContextURL.
+
+- General speed microimprovements for helloworld benchmark: replace
+  try/excepts with statements which use 'in' keyword.
+
+1.1a3 (2009-09-16)
+==================
+
+Documentation
+-------------
+
+- The "Views" narrative chapter in the documentation has been updated
+  extensively to discuss "renderers".
+
+Features
+--------
+
+- A ``renderer`` attribute has been added to view configurations,
+  replacing the previous (1.1a2) version's ``template`` attribute.  A
+  "renderer" is an object which accepts the return value of a view and
+  converts it to a string.  This includes, but is not limited to,
+  templating systems.
+
+- A new interface named ``IRenderer`` was added.  The existing
+  interface, ``ITemplateRenderer`` now derives from this new
+  interface.  This interface is internal.
+
+- A new interface named ``IRendererFactory`` was added.  An existing
+  interface named ``ITemplateRendererFactory`` now derives from this
+  interface.  This interface is internal.
+
+- The ``view`` attribute of the ``view`` ZCML directive is no longer
+  required if the ZCML directive also has a ``renderer`` attribute.
+  This is useful when the renderer is a template renderer and no names
+  need be passed to the template at render time.
+
+- A new zcml directive ``renderer`` has been added.  It is documented
+  in the "Views" narrative chapter of the documentation.
+
+- A ZCML ``view`` directive (and the associated ``bfg_view``
+  decorator) can now accept a "wrapper" value.  If a "wrapper" value
+  is supplied, it is the value of a separate view's *name* attribute.
+  When a view with a ``wrapper`` attribute is rendered, the "inner"
+  view is first rendered normally.  Its body is then attached to the
+  request as "wrapped_body", and then a wrapper view name is looked up
+  and rendered (using ``repoze.bfg.render_view_to_response``), passed
+  the request and the context.  The wrapper view is assumed to do
+  something sensible with ``request.wrapped_body``, usually inserting
+  its structure into some other rendered template.  This feature makes
+  it possible to specify (potentially nested) "owrap" relationships
+  between views using only ZCML or decorators (as opposed always using
+  ZPT METAL and analogues to wrap view renderings in outer wrappers).
+
+Dependencies
+------------
+
+- When used under Python < 2.6, BFG now has an installation time
+  dependency on the ``simplejson`` package.
+
+Deprecations
+------------
+
+- The ``repoze.bfg.testing.registerDummyRenderer`` API has been
+  deprecated in favor of
+  ``repoze.bfg.testing.registerTemplateRenderer``.  A deprecation
+  warning is *not* issued at import time for the former name; it will
+  exist "forever"; its existence has been removed from the
+  documentation, however.
+
+- The ``repoze.bfg.templating.renderer_from_cache`` function has been
+  moved to ``repoze.bfg.renderer.template_renderer_factory``.  This
+  was never an API, but code in the wild was spotted that used it.  A
+  deprecation warning is issued at import time for the former.
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``ITemplateRenderer`` interface has been changed.  Previously
+  its ``__call__`` method accepted ``**kw``.  It now accepts a single
+  positional parameter named ``kw`` (REVISED: it accepts two
+  positional parameters as of 1.1a4: ``value`` and ``system``).  This
+  is mostly an internal change, but it was exposed in APIs in one
+  place: if you've used the
+  ``repoze.bfg.testing.registerDummyRenderer`` API in your tests with
+  a custom "renderer" argument with your own renderer implementation,
+  you will need to change that renderer implementation to accept
+  ``kw`` instead of ``**kw`` in its ``__call__`` method (REVISED: make
+  it accept ``value`` and ``system`` positional arguments as of 1.1a4).
+
+- The ``ITemplateRendererFactory`` interface has been changed.
+  Previously its ``__call__`` method accepted an ``auto_reload``
+  keyword parameter.  Now its ``__call__`` method accepts no keyword
+  parameters.  Renderers are now themselves responsible for
+  determining details of auto-reload.  This is purely an internal
+  change.  This interface was never external.
+
+- The ``template_renderer`` ZCML directive introduced in 1.1a2 has
+  been removed.  It has been replaced by the ``renderer`` directive.
+
+- The previous release (1.1a2) added a view configuration attribute
+  named ``template``.  In this release, the attribute has been renamed
+  to ``renderer``.  This signifies that the attribute is more generic:
+  it can now be not just a template name but any renderer name (ala
+  ``json``).  
+
+- In the previous release (1.1a2), the Chameleon text template
+  renderer was used if the system didn't associate the ``template``
+  view configuration value with a filename with a "known" extension.
+  In this release, you must use a ``renderer`` attribute which is a
+  path that ends with a ``.txt`` extension
+  (e.g. ``templates/foo.txt``) to use the Chameleon text renderer.
+
+1.1a2 (2009-09-14)
+==================
+
+Features
+--------
+
+- A ZCML ``view`` directive (and the associated ``bfg_view``
+  decorator) can now accept an "attr" value.  If an "attr" value is
+  supplied, it is considered a method named of the view object to be
+  called when the response is required.  This is typically only good
+  for views that are classes or instances (not so useful for
+  functions, as functions typically have no methods other than
+  ``__call__``).
+
+- A ZCML ``view`` directive (and the associated ``bfg_view``
+  decorator) can now accept a "template" value.  If a "template" value
+  is supplied, and the view callable returns a dictionary, the
+  associated template is rendered with the dictionary as keyword
+  arguments.  See the section named "Views That Have a ``template``"
+  in the "Views" narrative documentation chapter for more information.
+
+1.1a1 (2009-09-06)
+==================
+
+Bug Fixes
+---------
+
+- "tests" module removed from the bfg_alchemy paster template; these
+  tests didn't work.
+
+- Bugfix: the ``discriminator`` for the ZCML "route" directive was
+  incorrect.  It was possible to register two routes that collided
+  without the system spitting out a ConfigurationConflictError at
+  startup time.
+
+Features
+--------
+
+- Feature addition: view predicates.  These are exposed as the
+  ``request_method``, ``request_param``, and ``containment``
+  attributes of a ZCML ``view`` declaration, or the respective
+  arguments to a ``@bfg_view`` decorator.  View predicates can be used
+  to register a view for a more precise set of environment parameters
+  than was previously possible.  For example, you can register two
+  views with the same ``name`` with different ``request_param``
+  attributes.  If the ``request.params`` dict contains 'foo'
+  (request_param="foo"), one view might be called; if it contains
+  'bar' (request_param="bar"), another view might be called.
+  ``request_param`` can also name a key/value pair ala ``foo=123``.
+  This will match only when the ``foo`` key is in the request.params
+  dict and it has the value '123'.  This particular example makes it
+  possible to write separate view functions for different form
+  submissions.  The other predicates, ``containment`` and
+  ``request_method`` work similarly.  ``containment`` is a view
+  predicate that will match only when the context's graph lineage has
+  an object possessing a particular class or interface, for example.
+  ``request_method`` is a view predicate that will match when the HTTP
+  ``REQUEST_METHOD`` equals some string (eg. 'POST').
+
+- The ``@bfg_view`` decorator now accepts three additional arguments:
+  ``request_method``, ``request_param``, and ``containment``.
+  ``request_method`` is used when you'd like the view to match only a
+  request with a particular HTTP ``REQUEST_METHOD``; a string naming
+  the ``REQUEST_METHOD`` can also be supplied as ``request_type`` for
+  backwards compatibility.  ``request_param`` is used when you'd like
+  a view to match only a request that contains a particular
+  ``request.params`` key (with or without a value).  ``containment``
+  is used when you'd like to match a request that has a context that
+  has some class or interface in its graph lineage.  These are
+  collectively known as "view predicates".
+
+- The ``route`` ZCML directive now honors ``view_request_method``,
+  ``view_request_param`` and ``view_containment`` attributes, which
+  pass along these values to the associated view if any is provided.
+  Additionally, the ``request_type`` attribute can now be spelled as
+  ``view_request_type``, and ``permission`` can be spelled as
+  ``view_permission``.  Any attribute which starts with ``view_`` can
+  now be spelled without the ``view_`` prefix, so ``view_for`` can be
+  spelled as ``for`` now, etc.  Both forms are documented in the
+  urldispatch narraitve documentation chapter.
+
+- The ``request_param`` ZCML view directive attribute (and its
+  ``bfg_view`` decorator cousin) can now specify both a key and a
+  value.  For example, ``request_param="foo=123"`` means that the foo
+  key must have a value of ``123`` for the view to "match".
+
+- Allow ``repoze.bfg.traversal.find_interface`` API to use a class
+  object as the argument to compare against the ``model`` passed in.
+  This means you can now do ``find_interface(model, SomeClass)`` and
+  the first object which is found in the lineage which has
+  ``SomeClass`` as its class (or the first object found which has
+  ``SomeClass`` as any of its superclasses) will be returned.
+
+- Added ``static`` ZCML directive which registers a route for a view
+  that serves up files in a directory.  See the "Views" narrative
+  documentation chapter's "Serving Static Resources Using a ZCML
+  Directive" section for more information.
+
+- The ``repoze.bfg.view.static`` class now accepts a string as its
+  first argument ("root_dir") that represents a package-relative name
+  e.g. ``somepackage:foo/bar/static``.  This is now the preferred
+  mechanism for spelling package-relative static paths using this
+  class.  A ``package_name`` keyword argument has been left around for
+  backwards compatibility.  If it is supplied, it will be honored.
+
+- The API ``repoze.bfg.testing.registerView`` now takes a
+  ``permission`` argument.  Use this instead of using
+  ``repoze.bfg.testing.registerViewPermission``.
+
+- The ordering of route declarations vs. the ordering of view
+  declarations that use a "route_name" in ZCML no longer matters.
+  Previously it had been impossible to use a route_name from a route
+  that had not yet been defined in ZCML (order-wise) within a "view"
+  declaration.
+
+- The repoze.bfg router now catches both
+  ``repoze.bfg.security.Unauthorized`` and
+  ``repoze.bfg.view.NotFound`` exceptions while rendering a view.
+  When the router catches an ``Unauthorized``, it returns the
+  registered forbidden view.  When the router catches a ``NotFound``,
+  it returns the registered notfound view.
+
+Internal
+--------
+
+- Change urldispatch internals: Route object is now constructed using
+  a path, a name, and a factory instead of a name, a matcher, a
+  generator, and a factory.
+
+- Move (non-API) default_view, default_forbidden_view, and
+  default_notfound_view functions into the ``repoze.bfg.view`` module
+  (moved from ``repoze.bfg.router``).
+
+- Removed ViewPermissionFactory from ``repoze.bfg.security``.  View
+  permission checking is now done by registering and looking up an
+  ISecuredView.
+
+- The ``static`` ZCML directive now uses a custom root factory when
+  constructing a route.
+
+- The interface ``IRequestFactories`` was removed from the
+  repoze.bfg.interfaces module.  This interface was never an API.
+
+- The function named ``named_request_factories`` and the data
+  structure named ``DEFAULT_REQUEST_FACTORIES`` have been removed from
+  the ``repoze.bfg.request`` module.  These were never APIs.
+
+- The ``IViewPermissionFactory`` interface has been removed.  This was
+  never an API.
+
+Documentation
+-------------
+
+- Request-only-convention examples in the "Views" narrative
+  documentation were broken.
+
+- Fixed documentation bugs related to forget and remember in security API
+  docs.
+
+- Fixed documentation for ``repoze.bfg.view.static`` (in narrative
+  ``Views`` chapter).
+
+Deprecations
+------------
+
+- The API ``repoze.bfg.testing.registerViewPermission`` has been
+  deprecated.
+
+Backwards Incompatibilities
+---------------------------
+
+- The interfaces ``IPOSTRequest``, ``IGETRequest``, ``IPUTRequest``,
+  ``IDELETERequest``, and ``IHEADRequest`` have been removed from the
+  ``repoze.bfg.interfaces`` module.  These were not documented as APIs
+  post-1.0.  Instead of using one of these, use a ``request_method``
+  ZCML attribute or ``request_method`` bfg_view decorator parameter
+  containing an HTTP method name (one of ``GET``, ``POST``, ``HEAD``,
+  ``PUT``, ``DELETE``) instead of one of these interfaces if you were
+  using one explicitly.  Passing a string in the set (``GET``,
+  ``HEAD``, ``PUT``, ``POST``, ``DELETE``) as a ``request_type``
+  argument will work too.  Rationale: instead of relying on interfaces
+  attached to the request object, BFG now uses a "view predicate" to
+  determine the request type.
+
+- Views registered without the help of the ZCML ``view`` directive are
+  now responsible for performing their own authorization checking.
+
+- The ``registry_manager`` backwards compatibility alias importable
+  from "repoze.bfg.registry", deprecated since repoze.bfg 0.9 has been
+  removed.  If you are tring to use the registry manager within a
+  debug script of your own, use a combination of the
+  "repoze.bfg.paster.get_app" and "repoze.bfg.scripting.get_root" APIs
+  instead.
+
+- The ``INotFoundAppFactory`` interface has been removed; it has
+  been deprecated since repoze.bfg 0.9.  If you have something like
+  the following in your ``configure.zcml``::
+
+   <utility provides="repoze.bfg.interfaces.INotFoundAppFactory"
+            component="helloworld.factories.notfound_app_factory"/>
+
+  Replace it with something like::
+
+   <notfound 
+       view="helloworld.views.notfound_view"/>
+
+  See "Changing the Not Found View" in the "Hooks" chapter of the
+  documentation for more information.
+
+- The ``IUnauthorizedAppFactory`` interface has been removed; it has
+  been deprecated since repoze.bfg 0.9.  If you have something like
+  the following in your ``configure.zcml``::
+
+   <utility provides="repoze.bfg.interfaces.IUnauthorizedAppFactory"
+            component="helloworld.factories.unauthorized_app_factory"/>
+
+  Replace it with something like::
+
+   <forbidden
+       view="helloworld.views.forbidden_view"/>
+
+  See "Changing the Forbidden View" in the "Hooks" chapter of the
+  documentation for more information.
+
+- ``ISecurityPolicy``-based security policies, deprecated since
+  repoze.bfg 0.9, have been removed.  If you have something like this
+  in your ``configure.zcml``, it will no longer work::
+
+     <utility
+       provides="repoze.bfg.interfaces.ISecurityPolicy"
+       factory="repoze.bfg.security.RemoteUserInheritingACLSecurityPolicy"
+      />
+
+  If ZCML like the above exists in your application, you will receive
+  an error at startup time.  Instead of the above, you'll need
+  something like::
+
+     <remoteuserauthenticationpolicy/>
+     <aclauthorizationpolicy/>
+
+  This is just an example.  See the "Security" chapter of the
+  repoze.bfg documentation for more information about configuring
+  security policies.
+
+- Custom ZCML directives which register an authentication or
+  authorization policy (ala "authtktauthenticationpolicy" or
+  "aclauthorizationpolicy") should register the policy "eagerly" in
+  the ZCML directive instead of from within a ZCML action.  If an
+  authentication or authorization policy is not found in the component
+  registry by the view machinery during deferred ZCML processing, view
+  security will not work as expected.
+
+1.0.1 (2009-07-22)
+==================
+
+- Added support for ``has_resource``, ``resource_isdir``, and
+  ``resource_listdir`` to the resource "OverrideProvider"; this fixes
+  a bug with a symptom that a file could not be overridden in a
+  resource directory unless a file with the same name existed in the
+  original directory being overridden.
+
+- Fixed documentation bug showing invalid test for values from the
+  ``matchdict``:  they are stored as attributes of the ``Article``, rather
+  than subitems.
+
+- Fixed documentation bug showing wrong environment key for the ``matchdict``
+  produced by the matching route.
+
+- Added a workaround for a bug in Python 2.6, 2.6.1, and 2.6.2 having
+  to do with a recursion error in the mimetypes module when trying to
+  serve static files from Paste's FileApp:
+  http://bugs.python.org/issue5853.  Symptom: File
+  "/usr/lib/python2.6/mimetypes.py", line 244, in guess_type return
+  guess_type(url, strict) RuntimeError: maximum recursion depth
+  exceeded.  Thanks to Armin Ronacher for identifying the symptom and
+  pointing out a fix.
+
+- Minor edits to tutorials for accuracy based on feedback.
+
+- Declared Paste and PasteDeploy dependencies.
+
+1.0 (2009-07-05)
+================
+
+- Retested and added some content to GAE tutorial.
+
+- Edited "Extending" narrative docs chapter.
+
+- Added "Deleting the Database" section to the "Defining Models"
+  chapter of the traversal wiki tutorial.
+
+- Spell checking of narratives and tutorials.
+
+1.0b2 (2009-07-03)
+==================
+
+- ``remoteuserauthenticationpolicy`` ZCML directive didn't work
+  without an ``environ_key`` directive (didn't match docs).
+
+- Fix ``configure_zcml`` filespec check on Windows.  Previously if an
+  absolute filesystem path including a drive letter was passed as
+  ``filename`` (or as ``configure_zcml`` in the options dict) to
+  ``repoze.bfg.router.make_app``, it would be treated as a
+  package:resource_name specification.
+
+- Fix inaccuracies and import errors in bfgwiki (traversal+ZODB) and
+  bfgwiki2 (urldispatch+SA) tutorials.
+
+- Use bfgsite index for all tutorial setup.cfg files.
+
+- Full documentation grammar/style/spelling audit.
+
+1.0b1 (2009-07-02)
+==================
+
+Features
+--------
+
+- Allow a Paste config file (``configure_zcml``) value or an
+  environment variable (``BFG_CONFIGURE_ZCML``) to name a ZCML file
+  (optionally package-relative) that will be used to bootstrap the
+  application.  Previously, the integrator could not influence which
+  ZCML file was used to do the boostrapping (only the original
+  application developer could do so).
+
+Documentation
+-------------
+
+- Added a "Resources" chapter to the narrative documentation which
+  explains how to override resources within one package from another
+  package.
+
+- Added an "Extending" chapter to the narrative documentation which
+  explains how to extend or modify an existing BFG application using
+  another Python package and ZCML.
+
+1.0a9 (2009-07-01)
+==================
+
+Features
+--------
+
+- Make it possible to pass strings in the form
+  "package_name:relative/path" to APIs like ``render_template``,
+  ``render_template_to_response``, and ``get_template``.  Sometimes
+  the package in which a caller lives is a direct namespace package,
+  so the module which is returned is semi-useless for navigating from.
+  In this way, the caller can control the horizontal and vertical of
+  where things get looked up from.
+
+1.0a8 (2009-07-01)
+==================
+
+Deprecations
+------------
+
+- Deprecate the ``authentication_policy`` and ``authorization_policy``
+  arguments to ``repoze.bfg.router.make_app``.  Instead, developers
+  should use the various authentication policy ZCML directives
+  (``repozewho1authenticationpolicy``,
+  ``remoteuserauthenticationpolicy`` and
+  ``authtktauthenticationpolicy``) and the `aclauthorizationpolicy``
+  authorization policy directive as described in the changes to the
+  "Security" narrative documenation chapter and the wiki tutorials.
+
+Features
+--------
+
+- Add three new ZCML directives which configure authentication
+  policies:
+
+  - ``repozewho1authenticationpolicy``
+
+  - ``remoteuserauthenticationpolicy``
+
+  - ``authtktauthenticationpolicy``
+
+- Add a new ZCML directive which configures an ACL authorization
+  policy named ``aclauthorizationpolicy``.
+
+Bug Fixes
+---------
+
+- Bug fix: when a ``repoze.bfg.resource.PackageOverrides`` class was
+  instantiated, and the package it was overriding already had a
+  ``__loader__`` attribute, it would fail at startup time, even if the
+  ``__loader__`` attribute was another PackageOverrides instance.  We
+  now replace any ``__loader__`` that is also a PackageOverrides
+  instance.  Symptom: ``ConfigurationExecutionError: <type
+  'exceptions.TypeError'>: Package <module 'karl.views' from
+  '/Users/chrism/projects/osi/bfgenv/src/karl/karl/views/__init__.pyc'>
+  already has a __loader__ (probably a module in a zipped egg)``.
+
+1.0a7 (2009-06-30)
+==================
+
+Features
+--------
+
+- Add a ``reload_resources`` configuration file setting (aka the
+  ``BFG_RELOAD_RESOURCES`` environment variable).  When this is set to
+  true, the server never needs to be restarted when moving files
+  between directory resource overrides (esp. for templates currently).
+
+- Add a ``reload_all`` configuration file setting (aka the
+  ``BFG_RELOAD_ALL`` environment variable) that implies both
+  ``reload_resources`` and ``reload_templates``.
+
+- The ``static`` helper view class now uses a ``PackageURLParser`` in
+  order to allow for the overriding of static resources (CSS / logo
+  files, etc) using the ``resource`` ZCML directive.  The
+  ``PackageURLParser`` class was added to a (new) ``static`` module in
+  BFG; it is a subclass of the ``StaticURLParser`` class in
+  ``paste.urlparser``.
+
+- The ``repoze.bfg.templating.renderer_from_cache`` function now
+  checks for the ``reload_resources`` setting; if it's true, it does
+  not register a template renderer (it won't use the registry as a
+  template renderer cache).
+
+Documentation
+-------------
+
+- Add ``pkg_resources`` to the glossary.
+
+- Update the "Environment" docs to note the existence of
+  ``reload_resources`` and ``reload_all``.
+
+- Updated the ``bfg_alchemy`` paster template to include two views:
+  the view on the root shows a list of links to records;  the view on
+  a record shows the details for that object.
+
+Internal
+--------
+
+- Use a colon instead of a tab as the separator between package name
+  and relpath to form the "spec" when register a ITemplateRenderer.
+
+- Register a ``repoze.bfg.resource.OverrideProvider`` as a
+  pkg_resources provider only for modules which are known to have
+  overrides, instead of globally, when a <resource> directive is used
+  (performance).
+
+1.0a6 (2009-06-29)
+==================
+
+Bug Fixes
+---------
+
+- Use ``caller_package`` function instead of ``caller_module``
+  function within ``templating`` to avoid needing to name the caller
+  module in resource overrides (actually match docs).
+
+- Make it possible to override templates stored directly in a module
+  with templates in a subdirectory of the same module, stored directly
+  within another module, or stored in a subdirectory of another module
+  (actually match docs).
+
+1.0a5 (2009-06-28)
+==================
+
+Features
+--------
+
+- A new ZCML directive exists named "resource".  This ZCML directive
+  allows you to override Chameleon templates within a package (both
+  directories full of templates and individual template files) with
+  other templates in the same package or within another package.  This
+  allows you to "fake out" a view's use of a template, causing it to
+  retrieve a different template than the one actually named by a
+  relative path to a call like
+  ``render_template_to_response('templates/mytemplate.pt')``.  For
+  example, you can override a template file by doing::
+
+    <resource
+      to_override="some.package:templates/mytemplate.pt"
+      override_with="another.package:othertemplates/anothertemplate.pt"
+     />
+
+  The string passed to "to_override" and "override_with" is named a
+  "specification".  The colon separator in a specification separates
+  the package name from a package-relative directory name.  The colon
+  and the following relative path are optional.  If they are not
+  specified, the override attempts to resolve every lookup into a
+  package from the directory of another package.  For example::
+
+    <resource
+      to_override="some.package"
+      override_with="another.package"
+     />
+
+
+  Individual subdirectories within a package can also be overridden::
+
+    <resource
+      to_override="some.package:templates/"
+      override_with="another.package:othertemplates/"
+     />
+
+  If you wish to override a directory with another directory, you must
+  make sure to attach the slash to the end of both the ``to_override``
+  specification and the ``override_with`` specification.  If you fail
+  to attach a slash to the end of a specification that points a
+  directory, you will get unexpected results.  You cannot override a
+  directory specification with a file specification, and vice versa (a
+  startup error will occur if you try).
+
+  You cannot override a resource with itself (a startup error will
+  occur if you try).
+
+  Only individual *package* resources may be overridden.  Overrides
+  will not traverse through subpackages within an overridden package.
+  This means that if you want to override resources for both
+  ``some.package:templates``, and ``some.package.views:templates``,
+  you will need to register two overrides.
+
+  The package name in a specification may start with a dot, meaning
+  that the package is relative to the package in which the ZCML file
+  resides.  For example::
+
+    <resource
+      to_override=".subpackage:templates/"
+      override_with="another.package:templates/"
+     />
+
+  Overrides for the same ``to_overrides`` specification can be named
+  multiple times within ZCML.  Each ``override_with`` path will be
+  consulted in the order defined within ZCML, forming an override
+  search path.
+
+  Resource overrides can actually override resources other than
+  templates.  Any software which uses the ``pkg_resources``
+  ``get_resource_filename``, ``get_resource_stream`` or
+  ``get_resource_string`` APIs will obtain an overridden file when an
+  override is used.  However, the only built-in facility which uses
+  the ``pkg_resources`` API within BFG is the templating stuff, so we
+  only call out template overrides here.
+
+- Use the ``pkg_resources`` API to locate template filenames instead
+  of dead-reckoning using the ``os.path`` module.
+
+- The ``repoze.bfg.templating`` module now uses ``pkg_resources`` to
+  locate and register template files instead of using an absolute
+  path name.
+
+1.0a4 (2009-06-25)
+==================
+
+Features
+--------
+
+- Cause ``:segment`` matches in route paths to put a Unicode-decoded
+  and URL-dequoted value in the matchdict for the value matched.
+  Previously a non-decoded non-URL-dequoted string was placed in the
+  matchdict as the value.
+
+- Cause ``*remainder`` matches in route paths to put a *tuple* in the
+  matchdict dictionary in order to be able to present Unicode-decoded
+  and URL-dequoted values for the traversal path.  Previously a
+  non-decoded non-URL-dequoted string was placed in the matchdict as
+  the value.
+
+- Add optional ``max_age`` keyword value to the ``remember`` method of
+  ``repoze.bfg.authentication.AuthTktAuthenticationPolicy``; if this
+  value is passed to ``remember``, the generated cookie will have a
+  corresponding Max-Age value.
+
+Documentation
+-------------
+
+- Add information to the URL Dispatch narrative documentation about
+  path pattern matching syntax.
+
+Bug Fixes
+---------
+
+- Make ``route_url`` URL-quote segment replacements during generation.
+  Remainder segments are not quoted.
+
+1.0a3 (2009-06-24)
+==================
+
+Implementation Changes
+----------------------
+
+- ``repoze.bfg`` no longer relies on the Routes package to interpret
+  URL paths.  All known existing ``path`` patterns will continue to
+  work with the reimplemented logic, which lives in
+  ``repoze.bfg.urldispatch``.  ``<route>`` ZCML directives which use
+  certain attributes (uncommon ones) may not work (see "Backwards
+  Incompatibilities" below).
+
+Bug Fixes
+---------
+
+- ``model_url`` when passed a request that was generated as a result
+  of a route match would fail in a call to ``route.generate``.
+
+- BFG-on-GAE didn't work due to a corner case bug in the fallback
+  Python implementation of ``threading.local`` (symptom:
+  "Initialization arguments are not supported").  Thanks to Michael
+  Bernstein for the bug report.
+
+Documentation
+-------------
+
+- Added a "corner case" explanation to the "Hybrid Apps" chapter
+  explaining what to do when "the wrong" view is matched.
+
+- Use ``repoze.bfg.url.route_url`` API in tutorials rather than Routes
+  ``url_for`` API.
+
+Features
+--------
+
+- Added the ``repoze.bfg.url.route_url`` API.  This API allows you to
+  generate URLs based on ``<route>`` declarations.  See the URL
+  Dispatch narrative chapter and the "repoze.bfg.url" module API
+  documentation for more information.
+
+Backwards Incompatibilities
+---------------------------
+
+- As a result of disusing Routes, using the Routes ``url_for`` API
+  inside a BFG application (as was suggested by previous iterations of
+  tutorials) will no longer work.  Use the
+  ``repoze.bfg.url.route_url`` method instead.
+
+- The following attributes on the ``<route>`` ZCML directive no longer
+  work: ``encoding``, ``static``, ``filter``, ``condition_method``,
+  ``condition_subdomain``, ``condition_function``, ``explicit``, or
+  ``subdomains``.  These were all Routes features.
+
+- The ``<route>`` ZCML directive no longer supports the
+  ``<requirement>`` subdirective.  This was a Routes feature.
+
+1.0a2 (2009-06-23)
+==================
+
+Bug Fixes
+---------
+
+- The ``bfg_routesalchemy`` paster template app tests failed due to a
+  mismatch between test and view signatures.
+
+Features
+--------
+
+- Add a ``view_for`` attribute to the ``route`` ZCML directive.  This
+  attribute should refer to an interface or a class (ala the ``for``
+  attribute of the ``view`` ZCML directive).
+
+Documentation
+-------------
+
+- Conditional documentation in installation section ("how to install a
+  Python interpreter").
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``callback`` argument of the ``repoze.bfg.authentication``
+  authentication policies named ``RepozeWho1AuthenticationPolicy``,
+  ``RemoteUserAuthenticationPolicy``, and
+  ``AuthTktAuthenticationPolicy`` now must accept two positional
+  arguments: the orginal argument accepted by each (userid or
+  identity) plus a second argument, which will be the current request.
+  Apologies, this is required to service finding groups when there is
+  no "global" database connection.
+
+1.0a1 (2009-06-22)
+==================
+
+Features
+--------
+
+- A new ZCML directive was added named ``notfound``.  This ZCML
+  directive can be used to name a view that should be invoked when the
+  request can't otherwise be resolved to a view callable.  For example::
+
+    <notfound 
+        view="helloworld.views.notfound_view"/>
+
+- A new ZCML directive was added named ``forbidden``.  This ZCML
+  directive can be used to name a view that should be invoked when a
+  view callable for a request is found, but cannot be invoked due to
+  an authorization failure.  For example::
+
+   <forbidden
+       view="helloworld.views.forbidden_view"/>
+
+- Allow views to be *optionally* defined as callables that accept only
+  a request object, instead of both a context and a request (which
+  still works, and always will).  The following types work as views in
+  this style:
+
+  - functions that accept a single argument ``request``, e.g.::
+
+      def aview(request):
+          pass
+
+  - new and old-style classes that have an ``__init__`` method that
+    accepts ``self, request``, e.g.::
+
+      def View(object):
+          __init__(self, request):
+             pass
+
+  - Arbitrary callables that have a ``__call__`` method that accepts
+    ``self, request``, e.g.::
+
+      def AView(object):
+          def __call__(self, request):
+             pass
+      view = AView()
+
+  This likely should have been the calling convention all along, as
+  the request has ``context`` as an attribute already, and with views
+  called as a result of URL dispatch, having the context in the
+  arguments is not very useful.  C'est la vie.
+
+- Cache the absolute path in the caller's package globals within
+  ``repoze.bfg.path`` to get rid of repeated (expensive) calls to
+  os.path.abspath.
+
+- Add ``reissue_time`` and ``timeout`` parameters to
+  ``repoze.bfg.authentication.AuthTktAuthenticationPolicy``
+  constructor.  If these are passed, cookies will be reset every so
+  often (cadged from the same change to repoze.who lately).
+
+- The matchdict related to the matching of a Routes route is available
+  on the request as the ``matchdict`` attribute:
+  ``request.matchdict``.  If no route matched, this attribute will be
+  None.
+
+- Make 404 responses slightly cheaper by showing
+  ``environ["PATH_INFO"]`` on the notfound result page rather than the
+  fullly computed URL.
+
+- Move LRU cache implementation into a separate package
+  (``repoze.lru``).
+
+- The concepts of traversal and URL dispatch have been unified.  It is
+  now possible to use the same sort of factory as both a traversal
+  "root factory" and what used to be referred to as a urldispatch
+  "context factory".
+
+- When the root factory argument (as a first argument) passed to
+  ``repoze.bfg.router.make_app`` is ``None``, a *default* root factory
+  is used.  This is in support of using routes as "root finders"; it
+  supplants the idea that there is a default
+  ``IRoutesContextFactory``.
+
+- The `view`` ZCML statement and the ``repoze.bfg.view.bfg_view``
+  decorator now accept an extra argument: ``route_name``.  If a
+  ``route_name`` is specified, it must match the name of a previously
+  defined ``route`` statement.  When it is specified, the view will
+  only be called when that route matches during a request.
+
+- It is now possible to perfom traversal *after* a route has matched.
+  Use the pattern ``*traverse`` in a ``<route>`` ``path`` attribute
+  within ZCML, and the path remainder which it matches will be used as
+  a traversal path.
+
+- When any route defined matches, the WSGI environment will now
+  contain a key ``bfg.routes.route`` (the Route object which matched),
+  and a key ``bfg.routes.matchdict`` (the result of calling route.match).
+
+Deprecations
+------------
+
+- Utility registrations against
+  ``repoze.bfg.interfaces.INotFoundView`` and
+  ``repoze.bfg.interfaces.IForbiddenView`` are now deprecated.  Use
+  the ``notfound`` and ``forbidden`` ZCML directives instead (see the
+  "Hooks" chapter for more information).  Such registrations will
+  continue to work, but the notfound and forbidden directives do
+  "extra work" to ensure that the callable named by the directive can
+  be called by the router even if it's a class or
+  request-argument-only view.
+
+Removals
+--------
+
+- The ``IRoutesContext``, ``IRoutesContextFactory``, and
+  ``IContextNotFound`` interfaces were removed from
+  ``repoze.bfg.interfaces``.  These were never APIs.
+
+- The ``repoze.bfg.urldispatch.RoutesContextNotFound``,
+  ``repoze.bfg.urldispatch.RoutesModelTraverser`` and
+  ``repoze.bfg.urldispatch.RoutesContextURL`` classes were removed.
+  These were also never APIs.
+
+Backwards Incompatibilities
+---------------------------
+
+- Moved the ``repoze.bfg.push`` module, which implemented the ``pushpage``
+  decorator, into a separate distribution, ``repoze.bfg.pushpage``.
+  Applications which used this decorator should continue to work after
+  adding that distribution to their installation requirements.
+
+- Changing the default request factory via an IRequestFactory utility
+  registration (as used to be documented in the "Hooks" chapter's
+  "Changing the request factory" section) is no longer supported.  The
+  dance to manufacture a request is complicated as a result of
+  unifying traversal and url dispatch, making it highly unlikely for
+  anyone to be able to override it properly.  For those who just want
+  to decorate or modify a request, use a NewRequestEvent subscriber
+  (see the Events chapter in the documentation).
+
+- The ``repoze.bfg.IRequestFactory`` interface was removed.  See the
+  bullet above for why.
+
+- Routes "context factories" (spelled as the factory argument to a
+  route statement in ZCML) must now expect the WSGI environ as a
+  single argument rather than a set of keyword arguments.  They can
+  obtain the match dictionary by asking for
+  environ['bfg.routes.matchdict'].  This is the same set of keywords
+  that used to be passed to urldispatch "context factories" in BFG 0.9
+  and below.
+
+- Using the ``@zope.component.adapter`` decorator on a bfg view
+  function no longer works.  Use the ``@repoze.bfg.view.bfg_view``
+  decorator instead to mark a function (or a class) as a view.
+
+- The name under which the matching route object is found in the
+  environ was changed from ``bfg.route`` to ``bfg.routes.route``.
+
+- Finding the root is now done *before* manufacturing a request object
+  (and sending a new request event) within the router (it used to be
+  performed afterwards).
+
+- Adding ``*path_info`` to a route no longer changes the PATH_INFO for
+  a request that matches using URL dispatch.  This feature was only
+  there to service the ``repoze.bfg.wsgi.wsgiapp2`` decorator and it
+  did it wrong; use ``*subpath`` instead now.
+
+- The values of ``subpath``, ``traversed``, and ``virtual_root_path``
+  attached to the request object are always now tuples instead of
+  lists (performance).
+
+Bug Fixes
+---------
+
+- The ``bfg_alchemy`` Paster template named "repoze.tm" in its
+  pipeline rather than "repoze.tm2", causing the startup to fail.
+
+- Move BBB logic for registering an
+  IAuthenticationPolicy/IForbiddenView/INotFoundView based on older
+  concepts from the router module's ``make_app`` function into the
+  ``repoze.bfg.zcml.zcml_configure`` callable, to service
+  compatibility with scripts that use "zope.configuration.xmlconfig"
+  (replace with ``repoze.bfg.zml.zcml_configure`` as necessary to get
+  BBB logic)
+
+Documentation
+-------------
+
+- Add interface docs related to how to create authentication policies
+  and authorization policies to the "Security" narrative chapter.
+
+- Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter
+  to the narrative documentation.  This explains the usage of
+  ``*traverse`` and ``*subpath`` in routes URL patters.
+
+- A "router" chapter explaining the request/response lifecycle at a
+  high level was added.
+
+- Replaced all mentions and explanations of a routes "context factory"
+  with equivalent explanations of a "root factory" (context factories
+  have been disused).
+
+- Updated Routes bfgwiki2 tutorial to reflect the fact that context
+  factories are now no longer used.
+
+0.9.1 (2009-06-02)
+==================
+
+Features
+--------
+
+- Add API named ``repoze.bfg.settings.get_settings`` which retrieves a
+  derivation of values passed as the ``options`` value of
+  ``repoze.bfg.router.make_app``.  This API should be preferred
+  instead of using getUtility(ISettings).  I added a new
+  ``repoze.bfg.settings`` API document as well.
+
+Bug Fixes
+---------
+
+- Restored missing entry point declaration for bfg_alchemy paster
+  template, which was accidentally removed in 0.9.
+
+Documentation
+-------------
+
+- Fix a reference to ``wsgiapp`` in the ``wsgiapp2`` API documentation
+  within the ``repoze.bfg.wsgi`` module.
+
+API Removals
+------------
+
+- The ``repoze.bfg.location.locate`` API was removed: it didn't do
+  enough to be very helpful and had a misleading name.
+
+0.9 (2009-06-01)
+================
+
+Bug Fixes
+---------
+
+- It was not possible to register a custom ``IRoutesContextFactory``
+  for use as a default context factory as documented in the "Hooks"
+  chapter.
+
+Features
+--------
+
+- The ``request_type`` argument of ZCML ``view`` declarations and
+  ``bfg_view`` decorators can now be one of the strings ``GET``,
+  ``POST``, ``PUT``, ``DELETE``, or ``HEAD`` instead of a reference to
+  the respective interface type imported from
+  ``repoze.bfg.interfaces``.
+
+- The ``route`` ZCML directive now accepts ``request_type`` as an
+  alias for its ``condition_method`` argument for symmetry with the
+  ``view`` directive.
+
+- The ``bfg_routesalchemy`` paster template now provides a unit test
+  and actually uses the database during a view rendering.
+
+Removals
+--------
+
+- Remove ``repoze.bfg.threadlocal.setManager``.  It was only used in
+  unit tests.
+
+- Remove ``repoze.bfg.wsgi.HTTPException``,
+  ``repoze.bfg.wsgi.NotFound``, and ``repoze.bfg.wsgi.Unauthorized``.
+  These classes were disused with the introduction of the
+  ``IUnauthorizedView`` and ``INotFoundView`` machinery.
+
+Documentation
+-------------
+
+- Add description to narrative templating chapter about how to use
+  Chameleon text templates.
+
+- Changed Views narrative chapter to use method strings rather than
+  interface types, and moved advanced interface type usage to Events
+  narrative chapter.
+
+- Added a Routes+SQLAlchemy wiki tutorial.
+
+0.9a8 (2009-05-31)
+==================
+
+Features
+--------
+
+- It is now possible to register a custom
+  ``repoze.bfg.interfaces.INotFoundView`` for a given application.
+  This feature replaces the
+  ``repoze.bfg.interfaces.INotFoundAppFactory`` feature previously
+  described in the Hooks chapter.  The INotFoundView will be called
+  when the framework detects that a view lookup done as a result of a
+  request fails; it should accept a context object and a request
+  object; it should return an IResponse object (a webob response,
+  basically).  See the Hooks narrative chapter of the BFG docs for
+  more info.
+
+- The error presented when a view invoked by the router returns a
+  non-response object now includes the view's name for troubleshooting
+  purposes.
+
+Bug Fixes
+---------
+
+- A "new response" event is emitted for forbidden and notfound views.
+
+Deprecations
+------------
+
+- The ``repoze.bfg.interfaces.INotFoundAppFactory`` interface has been
+  deprecated in favor of using the new
+  ``repoze.bfg.interfaces.INotFoundView`` mechanism.
+
+Renames
+-------
+
+- Renamed ``repoze.bfg.interfaces.IForbiddenResponseFactory`` to
+  ``repoze.bfg.interfaces.IForbiddenView``.
+
+0.9a7 (2009-05-30)
+==================
+
+Features
+--------
+
+- Remove "context" argument from ``effective_principals`` and
+  ``authenticated_userid`` function APIs in ``repoze.bfg.security``,
+  effectively a doing reversion to 0.8 and before behavior.  Both
+  functions now again accept only the ``request`` parameter.
+
+0.9a6 (2009-05-29)
+==================
+
+Documentation
+-------------
+
+- Changed "BFG Wiki" tutorial to use AuthTktAuthenticationPolicy
+  rather than repoze.who.
+
+Features
+--------
+
+- Add an AuthTktAuthenticationPolicy.  This policy retrieves
+  credentials from an auth_tkt cookie managed by the application
+  itself (instead of relying on an upstream data source for
+  authentication data).  See the Security API chapter of the
+  documentation for more info.
+
+- Allow RemoteUserAuthenticationPolicy and
+  RepozeWho1AuthenticationPolicy to accept various constructor
+  arguments.  See the Security API chapter of the documentation for
+  more info.
+
+0.9a5 (2009-05-28)
+==================
+
+Features
+--------
+
+- Add a ``get_app`` API functions to the ``paster`` module.  This
+  obtains a WSGI application from a config file given a config file
+  name and a section name.  See the ``repoze.bfg.paster`` API docs for
+  more information.
+
+- Add a new module named ``scripting``.  It contains a ``get_root``
+  API function, which, provided a Router instance, returns a traversal
+  root object and a "closer".  See the ``repoze.bfg.scripting`` API
+  docs for more info.
+
+0.9a4 (2009-05-27)
+==================
+
+Bug Fixes
+---------
+
+- Try checking for an "old style" security policy *after* we parse
+  ZCML (thinko).
+
+0.9a3 (2009-05-27)
+==================
+
+Features
+--------
+
+- Allow IAuthenticationPolicy and IAuthorizationPolicy to be
+  overridden via ZCML registrations (do ZCML parsing after
+  registering these in router.py).
+
+Documentation
+-------------
+
+- Added "BFG Wiki" tutorial to documentation; it describes
+  step-by-step how to create a traversal-based ZODB application with
+  authentication.
+
+Deprecations
+------------
+
+- Added deprecations for imports of ``ACLSecurityPolicy``,
+  ``InheritingACLSecurityPolicy``, ``RemoteUserACLSecurityPolicy``,
+  ``RemoteUserInheritingACLSecurityPolicy``, ``WhoACLSecurityPolicy``,
+  and ``WhoInheritingACLSecurityPolicy`` from the
+  ``repoze.bfg.security`` module; for the meantime (for backwards
+  compatibility purposes) these live in the ``repoze.bfg.secpols``
+  module.  Note however, that the entire concept of a "security
+  policy" is deprecated in BFG in favor of separate authentication and
+  authorization policies, so any use of a security policy will
+  generate additional deprecation warnings even if you do start using
+  ``repoze.bfg.secpols``.  ``repoze.bfg.secpols`` will disappear in a
+  future release of ``repoze.bfg``.
+
+Deprecated Import Alias Removals
+--------------------------------
+
+- Remove ``repoze.bfg.template`` module.  All imports from this
+  package have been deprecated since 0.3.8.  Instead, import
+  ``get_template``, ``render_template``, and
+  ``render_template_to_response`` from the
+  ``repoze.bfg.chameleon_zpt`` module. 
+
+- Remove backwards compatibility import alias for
+  ``repoze.bfg.traversal.split_path`` (deprecated since 0.6.5).  This
+  must now be imported as ``repoze.bfg.traversal.traversal_path``).
+
+- Remove backwards compatibility import alias for
+  ``repoze.bfg.urldispatch.RoutesContext`` (deprecated since 0.6.5).
+  This must now be imported as
+  ``repoze.bfg.urldispatch.DefaultRoutesContext``.
+
+- Removed backwards compatibility import aliases for
+  ``repoze.bfg.router.get_options`` and ``repoze.bfg.router.Settings``
+  (deprecated since 0.6.2).  These both must now be imported from
+  ``repoze.bfg.settings``.
+
+- Removed backwards compatibility import alias for
+  ``repoze.bfg.interfaces.IRootPolicy`` (deprecated since 0.6.2).  It
+  must be imported as ``repoze.bfg.interfaces.IRootFactory`` now.
+
+- Removed backwards compatibility import alias for
+  ``repoze.bfg.interfaces.ITemplate`` (deprecated since 0.4.4).  It
+  must be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` now.
+
+- Removed backwards compatibility import alias for
+  ``repoze.bfg.interfaces.ITemplateFactory`` (deprecated since 0.4.4).
+  It must be imported as
+  ``repoze.bfg.interfaces.ITemplateRendererFactory`` now.
+
+- Removed backwards compatibility import alias for
+  ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` (deprecated since
+  0.4.4).  This must be imported as ``repoze.bfg.ZPTTemplateRenderer``
+  now.
+
+0.9a2 (2009-05-27)
+==================
+
+Features
+--------
+
+- A paster command has been added named "bfgshell".  This command can
+  be used to get an interactive prompt with your BFG root object in
+  the global namespace.  E.g.::
+
+    bin/paster bfgshell /path/to/myapp.ini myapp
+
+  See the ``Project`` chapter in the BFG documentation for more
+  information.
+
+Deprecations
+------------
+
+- The name ``repoze.bfg.registry.registry_manager`` was never an API,
+  but scripts in the wild were using it to set up an environment for
+  use under a debug shell.  A backwards compatibility shim has been
+  added for this purpose, but the feature is deprecated.
+
+0.9a1 (2009-5-27)
+=================
+
+Features
+--------
+
+- New API functions named ``forget`` and ``remember`` are available in
+  the ``security`` module.  The ``forget`` function returns headers
+  which will cause the currently authenticated user to be logged out
+  when set in a response.  The ``remember`` function (when passed the
+  proper arguments) will return headers which will cause a principal
+  to be "logged in" when set in a response.  See the Security API
+  chapter of the docs for more info.
+
+- New keyword arguments to the ``repoze.bfg.router.make_app`` call
+  have been added: ``authentication_policy`` and
+  ``authorization_policy``.  These should, respectively, be an
+  implementation of an authentication policy (an object implementing
+  the ``repoze.bfg.interfaces.IAuthenticationPolicy`` interface) and
+  an implementation of an authorization policy (an object implementing
+  ``repoze.bfg.interfaces.IAuthorizationPolicy)``.  Concrete
+  implementations of authentication policies exist in
+  ``repoze.bfg.authentication``.  Concrete implementations of
+  authorization policies exist in ``repoze.bfg.authorization``.
+
+  Both ``authentication_policy`` and ``authorization_policy`` default
+  to ``None``.
+
+  If ``authentication_policy`` is ``None``, but
+  ``authorization_policy`` is *not* ``None``, then
+  ``authorization_policy`` is ignored (the ability to do authorization
+  depends on authentication).
+
+  If the ``authentication_policy`` argument is *not* ``None``, and the
+  ``authorization_policy`` argument *is* ``None``, the authorization
+  policy defaults to an authorization implementation that uses ACLs
+  (``repoze.bfg.authorization.ACLAuthorizationPolicy``).
+
+  We no longer encourage configuration of "security policies" using
+  ZCML, as previously we did for ``ISecurityPolicy``.  This is because
+  it's not uncommon to need to configure settings for concrete
+  authorization or authentication policies using paste .ini
+  parameters; the app entry point for your application is the natural
+  place to do this.
+
+- Two new abstractions have been added in the way of adapters used by
+  the system: an ``IAuthorizationPolicy`` and an
+  ``IAuthenticationPolicy``.  A combination of these (as registered by
+  the ``securitypolicy`` ZCML directive) take the place of the
+  ``ISecurityPolicy`` abstraction in previous releases of repoze.who.
+  The API functions in ``repoze.who.security`` (such as
+  ``authentication_userid``, ``effective_principals``,
+  ``has_permission``, and so on) have been changed to try to make use
+  of these new adapters.  If you're using an older ``ISecurityPolicy``
+  adapter, the system will still work, but it will print deprecation
+  warnings when such a policy is used.
+
+- The way the (internal) IViewPermission utilities registered via ZCML
+  are invoked has changed.  They are purely adapters now, returning a
+  boolean result, rather than returning a callable. You shouldn't have
+  been using these anyway. ;-)
+
+- New concrete implementations of IAuthenticationPolicy have been
+  added to the ``repoze.bfg.authentication`` module:
+  ``RepozeWho1AuthenticationPolicy`` which uses ``repoze.who``
+  identity to retrieve authentication data from and
+  ``RemoteUserAuthenticationPolicy``, which uses the ``REMOTE_USER``
+  value in the WSGI environment to retrieve authentication data.
+
+- A new concrete implementation of IAuthorizationPolicy has been added
+  to the ``repoze.bfg.authorization`` module:
+  ``ACLAuthorizationPolicy`` which uses ACL inheritance to do
+  authorization.
+
+- It is now possible to register a custom
+  ``repoze.bfg.interfaces.IForbiddenResponseFactory`` for a given
+  application.  This feature replaces the
+  ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` feature previously
+  described in the Hooks chapter.  The IForbiddenResponseFactory will
+  be called when the framework detects an authorization failure; it
+  should accept a context object and a request object; it should
+  return an IResponse object (a webob response, basically).  Read the
+  below point for more info and see the Hooks narrative chapter of the
+  BFG docs for more info.
+
+Backwards Incompatibilities
+---------------------------
+
+- Custom NotFound and Forbidden (nee' Unauthorized) WSGI applications
+  (registered as a utility for INotFoundAppFactory and
+  IUnauthorizedAppFactory) could rely on an environment key named
+  ``message`` describing the circumstance of the response.  This key
+  has been renamed to ``repoze.bfg.message`` (as per the WSGI spec,
+  which requires environment extensions to contain dots).
+
+Deprecations
+------------
+
+- The ``repoze.bfg.interfaces.IUnauthorizedAppFactory`` interface has
+  been deprecated in favor of using the new
+  ``repoze.bfg.interfaces.IForbiddenResponseFactory`` mechanism.
+
+- The ``view_execution_permitted`` API should now be imported from the
+  ``repoze.bfg.security`` module instead of the ``repoze.bfg.view``
+  module.
+
+- The ``authenticated_userid`` and ``effective_principals`` APIs in
+  ``repoze.bfg.security`` used to only take a single argument
+  (request).  They now accept two arguments (``context`` and
+  ``request``).  Calling them with a single argument is still
+  supported but issues a deprecation warning.  (NOTE: this change was
+  reverted in 0.9a7; meaning the 0.9 versions of these functions
+  again accept ``request`` only, just like 0.8 and before).
+
+- Use of "old-style" security policies (those base on ISecurityPolicy)
+  is now deprecated.  See the "Security" chapter of the docs for info
+  about activating an authorization policy and an authentication poicy.
+
+0.8.1 (2009-05-21)
+==================
+
+Features
+--------
+
+- Class objects may now be used as view callables (both via ZCML and
+  via use of the ``bfg_view`` decorator in Python 2.6 as a class
+  decorator).  The calling semantics when using a class as a view
+  callable is similar to that of using a class as a Zope "browser
+  view": the class' ``__init__`` must accept two positional parameters
+  (conventionally named ``context``, and ``request``).  The resulting
+  instance must be callable (it must have a ``__call__`` method).
+  When called, the instance should return a response.  For example::
+
+    from webob import Response
+
+    class MyView(object):
+        def __init__(self, context, request):
+            self.context = context
+            self.request = request
+
+        def __call__(self):
+            return Response('hello from %s!' % self.context)
+
+   See the "Views" chapter in the documentation and the
+   ``repoze.bfg.view`` API documentation for more information.
+
+- Removed the pickling of ZCML actions (the code that wrote
+  ``configure.zcml.cache`` next to ``configure.zcml`` files in
+  projects).  The code which managed writing and reading of the cache
+  file was a source of subtle bugs when users switched between
+  imperative (e.g. ``@bfg_view``) registrations and declarative
+  registrations (e.g. the ``view`` directive in ZCML) on the same
+  project. On a moderately-sized project (535 ZCML actions and 15 ZCML
+  files), executing actions read from the pickle was saving us only
+  about 200ms (2.5 sec vs 2.7 sec average). On very small projects (1
+  ZCML file and 4 actions), startup time was comparable, and sometimes
+  even slower when reading from the pickle, and both ways were so fast
+  that it really just didn't matter anyway.
+
+0.8 (2009-05-18)
+================
+
+Features
+--------
+
+- Added a ``traverse`` function to the ``repoze.bfg.traversal``
+  module.  This function may be used to retrieve certain values
+  computed during path resolution.  See the Traversal API chapter of
+  the documentation for more information about this function.
+
+Deprecations
+------------
+
+- Internal: ``ITraverser`` callables should now return a dictionary
+  rather than a tuple.  Up until 0.7.0, all ITraversers were assumed
+  to return a 3-tuple.  In 0.7.1, ITraversers were assumed to return a
+  6-tuple.  As (by evidence) it's likely we'll need to add further
+  information to the return value of an ITraverser callable, 0.8
+  assumes that an ITraverser return a dictionary with certain elements
+  in it.  See the ``repoze.bfg.interfaces.ITraverser`` interface for
+  the list of keys that should be present in the dictionary.
+  ``ITraversers`` which return tuples will still work, although a
+  deprecation warning will be issued.
+
+Backwards Incompatibilities
+---------------------------
+
+- If your code used the ITraverser interface directly (not via an API
+  function such as ``find_model``) via an adapter lookup, you'll need
+  to change your code to expect a dictionary rather than a 3- or
+  6-tuple if your code ever gets return values from the default
+  ModelGraphTraverser or RoutesModelTraverser adapters.
+
+0.8a7 (2009-05-16)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``RoutesMapper`` class in ``repoze.bfg.urldispatch`` has been
+  removed, as well as its documentation.  It had been deprecated since
+  0.6.3.  Code in ``repoze.bfg.urldispatch.RoutesModelTraverser``
+  which catered to it has also been removed.
+
+- The semantics of the ``route`` ZCML directive have been simplified.
+  Previously, it was assumed that to use a route, you wanted to map a
+  route to an externally registered view.  The new ``route`` directive
+  instead has a ``view`` attribute which is required, specifying the
+  dotted path to a view callable.  When a route directive is
+  processed, a view is *registered* using the name attribute of the
+  route directive as its name and the callable as its value.  The
+  ``view_name`` and ``provides`` attributes of the ``route`` directive
+  are therefore no longer used.  Effectively, if you were previously
+  using the ``route`` directive, it means you must change a pair of
+  ZCML directives that look like this::
+
+    <route
+       name="home"
+       path=""
+       view_name="login"
+       factory=".models.root.Root"
+     />
+
+    <view
+       for=".models.root.Root"
+       name="login"
+       view=".views.login_view"
+     />
+    
+  To a ZCML directive that looks like this::
+
+    <route
+       name="home"
+       path=""
+       view=".views.login_view"
+       factory=".models.root.Root"
+     />
+
+  In other words, to make old code work, remove the ``view``
+  directives that were only there to serve the purpose of backing
+  ``route`` directives, and move their ``view=`` attribute into the
+  ``route`` directive itself.
+
+  This change also necessitated that the ``name`` attribute of the
+  ``route`` directive is now required.  If you were previously using
+  ``route`` directives without a ``name`` attribute, you'll need to
+  add one (the name is arbitrary, but must be unique among all
+  ``route`` and ``view`` statements).
+
+  The ``provides`` attribute of the ``route`` directive has also been
+  removed.  This directive specified a sequence of interface types
+  that the generated context would be decorated with.  Since route
+  views are always generated now for a single interface
+  (``repoze.bfg.IRoutesContext``) as opposed to being looked up
+  arbitrarily, there is no need to decorate any context to ensure a
+  view is found.
+
+Documentation
+-------------
+
+- Added API docs for the ``repoze.bfg.testing`` methods
+  ``registerAdapter``, ``registerUtiity``, ``registerSubscriber``, and
+  ``cleanUp``.
+
+- Added glossary entry for "root factory".
+
+- Noted existence of ``repoze.bfg.pagetemplate`` template bindings in
+  "Available Add On Template System Bindings" in Templates chapter in
+  narrative docs.
+
+- Update "Templates" narrative chapter in docs (expand to show a
+  sample template and correct macro example).
+
+Features
+--------
+
+- Courtesty Carlos de la Guardia, added an ``alchemy`` Paster
+  template.  This paster template sets up a BFG project that uses
+  SQAlchemy (with SQLite) and uses traversal to resolve URLs.  (no
+  Routes areused).  This template can be used via ``paster create -t
+  bfg_alchemy``.
+
+- The Routes ``Route`` object used to resolve the match is now put
+  into the environment as ``bfg.route`` when URL dispatch is used.
+
+- You can now change the default Routes "context factory" globally.
+  See the "ZCML Hooks" chapter of the documentation (in the "Changing
+  the Default Routes Context Factory" section).
+
+0.8a6 (2009-05-11)
+==================
+
+Features
+--------
+
+- Added a ``routesalchemy`` Paster template.  This paster template
+  sets up a BFG project that uses SQAlchemy (with SQLite) and uses
+  Routes exclusively to resolve URLs (no traversal root factory is
+  used).  This template can be used via ``paster create -t
+  bfg_routesalchemy``.
+
+Documentation
+-------------
+
+- Added documentation to the URL Dispatch chapter about how to catch
+  the root URL using a ZCML ``route`` directive.
+
+- Added documentation to the URL Dispatch chapter about how to perform
+  a cleanup function at the end of a request (e.g. close the SQL
+  connection).
+
+Bug Fixes
+---------
+
+- In version 0.6.3, passing a ``get_root`` callback (a "root factory")
+  to ``repoze.bfg.router.make_app`` became optional if any ``route``
+  declaration was made in ZCML.  The intent was to make it possible to
+  disuse traversal entirely, instead relying entirely on URL dispatch
+  (Routes) to resolve all contexts.  However a compound set of bugs
+  prevented usage of a Routes-based root view (a view which responds
+  to "/").  One bug existed in `repoze.bfg.urldispatch``, another
+  existed in Routes itself.
+
+  To resolve this issue, the urldispatch module was fixed, and a fork
+  of the Routes trunk was put into the "dev" index named
+  ``Routes-1.11dev-chrism-home``.  The source for the fork exists at
+  `http://bitbucket.org/chrism/routes-home/
+  <http://bitbucket.org/chrism/routes-home/>`_ (broken link);
+  its contents have been merged into the Routes trunk
+  (what will be Routes 1.11).
+
+0.8a5 (2009-05-08)
+==================
+
+Features
+--------
+
+- Two new security policies were added:
+  RemoteUserInheritingACLSecurityPolicy and
+  WhoInheritingACLSecurityPolicy.  These are security policies which
+  take into account *all* ACLs defined in the lineage of a context
+  rather than stopping at the first ACL found in a lineage.  See the
+  "Security" chapter of the API documentation for more information.
+
+- The API and narrative documentation dealing with security was
+  changed to introduce the new "inheriting" security policy variants.
+
+- Added glossary entry for "lineage".
+
+Deprecations
+------------
+
+- The security policy previously named
+  ``RepozeWhoIdentityACLSecurityPolicy`` now has the slightly saner
+  name of ``WhoACLSecurityPolicy``.  A deprecation warning is emitted
+  when this policy is imported under the "old" name; usually this is
+  due to its use in ZCML within your application.  If you're getting
+  this deprecation warning, change your ZCML to use the new name,
+  e.g. change::
+
+   <utility
+     provides="repoze.bfg.interfaces.ISecurityPolicy"
+     factory="repoze.bfg.security.RepozeWhoIdentityACLSecurityPolicy"
+     />
+
+  To::
+
+   <utility
+     provides="repoze.bfg.interfaces.ISecurityPolicy"
+     factory="repoze.bfg.security.WhoACLSecurityPolicy"
+     />
+
+0.8a4 (2009-05-04)
+==================
+
+Features
+--------
+
+- ``zope.testing`` is no longer a direct dependency, although our
+  dependencies (such as ``zope.interface``, ``repoze.zcml``, etc)
+  still depend on it.
+
+- Tested on Google App Engine.  Added a tutorial to the documentation
+  explaining how to deploy a BFG app to GAE.
+
+Backwards Incompatibilities
+---------------------------
+
+- Applications which rely on ``zope.testing.cleanup.cleanUp`` in unit
+  tests can still use that function indefinitely.  However, for
+  maximum forward compatibility, they should import ``cleanUp`` from
+  ``repoze.bfg.testing`` instead of from ``zope.testing.cleanup``.
+  The BFG paster templates and docs have been changed to use this
+  function instead of the ``zope.testing.cleanup`` version.
+
+0.8a3 (2009-05-03)
+===================
+
+Features
+--------
+
+- Don't require a successful import of ``zope.testing`` at BFG
+  application runtime.  This allows us to get rid of ``zope.testing``
+  on platforms like GAE which have file limits.
+
+0.8a2 (2009-05-02)
+==================
+
+Features
+--------
+
+- We no longer include the ``configure.zcml`` of the ``chameleon.zpt``
+  package within the ``configure.zcml`` of the "repoze.bfg.includes"
+  package.  This has been a no-op for some time now.
+
+- The ``repoze.bfg.chameleon_zpt`` package no longer imports from
+  ``chameleon.zpt`` at module scope, deferring the import until later
+  within a method call.  The ``chameleon.zpt`` package can't be
+  imported on platforms like GAE.
+
+0.8a1 (2009-05-02)
+==================
+
+Deprecation Warning and Import Alias Removals
+---------------------------------------------
+
+- Since version 0.6.1, a deprecation warning has been emitted when the
+  name ``model_url`` is imported from the ``repoze.bfg.traversal``
+  module.  This import alias (and the deprecation warning) has been
+  removed.  Any import of the ``model_url`` function will now need to
+  be done from ``repoze.bfg.url``; any import of the name
+  ``model_url`` from ``repoze.bfg.traversal`` will now fail.  This was
+  done to remove a dependency on zope.deferredimport.
+
+- Since version 0.6.5, a deprecation warning has been emitted when the
+  name ``RoutesModelTraverser`` is imported from the
+  ``repoze.bfg.traversal`` module.  This import alias (and the
+  deprecation warning) has been removed.  Any import of the
+  ``RoutesModelTraverser`` class will now need to be done from
+  ``repoze.bfg.urldispatch``; any import of the name
+  ``RoutesModelTraverser`` from ``repoze.bfg.traversal`` will now
+  fail.  This was done to remove a dependency on zope.deferredimport.
+
+Features
+--------
+
+- This release of ``repoze.bfg`` is "C-free".  This means it has no
+  hard dependencies on any software that must be compiled from C
+  source at installation time.  In particular, ``repoze.bfg`` no
+  longer depends on the ``lxml`` package.
+
+  This change has introduced some backwards incompatibilities,
+  described in the "Backwards Incompatibilities" section below.
+
+- This release was tested on Windows XP.  It appears to work fine and
+  all the tests pass.
+
+Backwards Incompatibilities
+---------------------------
+
+Incompatibilities related to making ``repoze.bfg`` "C-free":
+
+- Removed the ``repoze.bfg.chameleon_genshi`` module, and thus support
+  for Genshi-style chameleon templates.  Genshi-style Chameleon
+  templates depend upon ``lxml``, which is implemented in C (as
+  opposed to pure Python) and the ``repoze.bfg`` core is "C-free" as
+  of this release. You may get Genshi-style Chameleon support back by
+  installing the ``repoze.bfg.chameleon_genshi`` package availalable
+  from http://svn.repoze.org/repoze.bfg.chameleon_genshi (also
+  available in the index at http://dist.repoze.org/bfg/0.8/simple).
+  All existing code that depended on the ``chameleon_genshi`` module
+  prior to this release of ``repoze.bfg`` should work without change
+  after this addon is installed.
+
+- Removed the ``repoze.bfg.xslt`` module and thus support for XSL
+  templates.  The ``repoze.bfg.xslt`` module depended upon ``lxml``,
+  which is implemented in C, and the ``repoze.bfg`` core is "C-free"
+  as of this release.  You bay get XSL templating back by installing
+  the ``repoze.bfg.xslt`` package available from
+  http://svn.repoze.org/repoze.bfg.xslt/ (also available in the index
+  at http://dist.repoze.org/bfg/0.8/simple).  All existing code that
+  depended upon the ``xslt`` module prior to this release of
+  ``repoze.bfg`` should work without modification after this addon is
+  installed.
+
+- Removed the ``repoze.bfg.interfaces.INodeTemplateRenderer``
+  interface and the an old b/w compat aliases from that interface to
+  ``repoze.bfg.interfaces.INodeTemplate``.  This interface must now be
+  imported from the ``repoze.bfg.xslt.interfaces`` package after
+  installation of the ``repoze.bfg.xslt`` addon package described
+  above as ``repoze.bfg.interfaces.INodeTemplateRenderer``.  This
+  interface was never part of any public API.
+
+Other backwards incompatibilities:
+
+- The ``render_template`` function in ``repoze.bfg.chameleon_zpt``
+  returns Unicode instead of a string.  Likewise, the individual
+  values returned by the iterable created by the
+  ``render_template_to_iterable`` function are also each Unicode.
+  This is actually a backwards incompatibility inherited from our new
+  use of the combination of ``chameleon.core`` 1.0b32 (the
+  non-lxml-depending version) and ``chameleon.zpt`` 1.0b16+ ; the
+  ``chameleon.zpt`` PageTemplateFile implementation used to return a
+  string, but now returns Unicode.
+
+0.7.1 (2009-05-01)
+==================
+
+Index-Related
+-------------
+
+- The canonical package index location for ``repoze.bfg`` has changed.
+  The "old" index (http://dist.repoze.org/lemonade/dev/simple) has
+  been superseded by a new index location
+  (`http://dist.repoze.org/bfg/current/simple
+  <http://dist.repoze.org/bfg/current/simple>`_).  The installation
+  documentation has been updated as well as the ``setup.cfg`` file in
+  this package.  The "lemonade" index still exists, but it is not
+  guaranteed to have the latest BFG software in it, nor will it be
+  maintained in the future.
+
+Features
+--------
+
+- The "paster create" templates have been modified to use links to the
+  new "bfg.repoze.org" and "docs.repoze.org" websites.
+
+- Added better documentation for virtual hosting at a URL prefix
+  within the virtual hosting docs chapter.
+
+- The interface for ``repoze.bfg.interfaces.ITraverser`` and the
+  built-in implementations that implement the interface
+  (``repoze.bfg.traversal.ModelGraphTraverser``, and
+  ``repoze.bfg.urldispatch.RoutesModelTraverser``) now expect the
+  ``__call__`` method of an ITraverser to return 3 additional
+  arguments: ``traversed``, ``virtual_root``, and
+  ``virtual_root_path`` (the old contract was that the ``__call__``
+  method of an ITraverser returned; three arguments, the contract new
+  is that it returns six).  ``traversed`` will be a sequence of
+  Unicode names that were traversed (including the virtual root path,
+  if any) or ``None`` if no traversal was performed, ``virtual_root``
+  will be a model object representing the virtual root (or the
+  physical root if traversal was not performed), and
+  ``virtual_root_path`` will be a sequence representing the virtual
+  root path (a sequence of Unicode names) or ``None`` if traversal was
+  not performed.
+
+  Six arguments are now returned from BFG ITraversers.  They are
+  returned in this order: ``context``, ``view_name``, ``subpath``,
+  ``traversed``, ``virtual_root``, and ``virtual_root_path``.
+
+  Places in the BFG code which called an ITraverser continue to accept
+  a 3-argument return value, although BFG will generate and log a
+  warning when one is encountered.
+
+- The request object now has the following attributes: ``traversed``
+  (the sequence of names traversed or ``None`` if traversal was not
+  performed), ``virtual_root`` (the model object representing the
+  virtual root, including the virtual root path if any), and
+  ``virtual_root_path`` (the seuquence of names representing the
+  virtual root path or ``None`` if traversal was not performed).
+
+- A new decorator named ``wsgiapp2`` was added to the
+  ``repoze.bfg.wsgi`` module.  This decorator performs the same
+  function as ``repoze.bfg.wsgi.wsgiapp`` except it fixes up the
+  ``SCRIPT_NAME``, and ``PATH_INFO`` environment values before
+  invoking the WSGI subapplication.
+
+- The ``repoze.bfg.testing.DummyRequest`` object now has default
+  attributes for ``traversed``, ``virtual_root``, and
+  ``virtual_root_path``.
+
+- The RoutesModelTraverser now behaves more like the Routes
+  "RoutesMiddleware" object when an element in the match dict is named
+  ``path_info`` (usually when there's a pattern like
+  ``http://foo/*path_info``).  When this is the case, the
+  ``PATH_INFO`` environment variable is set to the value in the match
+  dict, and the ``SCRIPT_NAME`` is appended to with the prefix of the
+  original ``PATH_INFO`` not including the value of the new variable.
+
+- The notfound debug now shows the traversed path, the virtual root,
+  and the virtual root path too.
+
+- Speed up / clarify 'traversal' module's 'model_path', 'model_path_tuple',
+  and '_model_path_list' functions.
+
+Backwards Incompatibilities
+---------------------------
+
+- In previous releases, the ``repoze.bfg.url.model_url``,
+  ``repoze.bfg.traversal.model_path`` and
+  ``repoze.bfg.traversal.model_path_tuple`` functions always ignored
+  the ``__name__`` argument of the root object in a model graph (
+  effectively replacing it with a leading ``/`` in the returned value)
+  when a path or URL was generated.  The code required to perform this
+  operation was not efficient.  As of this release, the root object in
+  a model graph *must* have a ``__name__`` attribute that is either
+  ``None`` or the empty string (``''``) for URLs and paths to be
+  generated properly from these APIs.  If your root model object has a
+  ``__name__`` argument that is not one of these values, you will need
+  to change your code for URLs and paths to be generated properly.  If
+  your model graph has a root node with a string ``__name__`` that is
+  not null, the value of ``__name__`` will be prepended to every path
+  and URL generated.
+
+- The ``repoze.bfg.location.LocationProxy`` class and the
+  ``repoze.bfg.location.ClassAndInstanceDescr`` class have both been
+  removed in order to be able to eventually shed a dependency on
+  ``zope.proxy``.  Neither of these classes was ever an API.
+
+- In all previous releases, the ``repoze.bfg.location.locate``
+  function worked like so: if a model did not explicitly provide the
+  ``repoze.bfg.interfaces.ILocation`` interface, ``locate`` returned a
+  ``LocationProxy`` object representing ``model`` with its
+  ``__parent__`` attribute assigned to ``parent`` and a ``__name__``
+  attribute assigned to ``__name__``.  In this release, the
+  ``repoze.bfg.location.locate`` function simply jams the ``__name__``
+  and ``__parent__`` attributes on to the supplied model
+  unconditionally, no matter if the object implements ILocation or
+  not, and it never returns a proxy.  This was done because the
+  LocationProxy behavior has now moved into an add-on package
+  (``repoze.bfg.traversalwrapper``), in order to eventually be able to
+  shed a dependency on ``zope.proxy``.
+
+- In all previous releases, by default, if traversal was used (as
+  opposed to URL-dispatch), and the root object supplied
+  the``repoze.bfg.interfaces.ILocation`` interface, but the children
+  returned via its ``__getitem__`` returned an object that did not
+  implement the same interface, ``repoze.bfg`` provided some
+  implicit help during traversal.  This traversal feature wrapped
+  subobjects from the root (and thereafter) that did not implement
+  ``ILocation`` in proxies which automatically provided them with a
+  ``__name__`` and ``__parent__`` attribute based on the name being
+  traversed and the previous object traversed.  This feature has now
+  been removed from the base ``repoze.bfg`` package for purposes of
+  eventually shedding a dependency on ``zope.proxy``.
+
+  In order to re-enable the wrapper behavior for older applications
+  which cannot be changed, register the "traversalwrapper"
+  ``ModelGraphTraverser`` as the traversal policy, rather than the
+  default ``ModelGraphTraverser``. To use this feature, you will need
+  to install the ``repoze.bfg.traversalwrapper`` package (an add-on
+  package, available at
+  http://svn.repoze.org/repoze.bfg.traversalwrapper) Then change your
+  application's ``configure.zcml`` to include the following stanza:
+
+    <adapter
+        factory="repoze.bfg.traversalwrapper.ModelGraphTraverser"
+        provides="repoze.bfg.interfaces.ITraverserFactory"
+        for="*"
+        />
+
+   When this ITraverserFactory is used instead of the default, no
+   object in the graph (even the root object) must supply a
+   ``__name__`` or ``__parent__`` attribute.  Even if subobjects
+   returned from the root *do* implement the ILocation interface,
+   these will still be wrapped in proxies that override the object's
+   "real" ``__parent__`` and ``__name__`` attributes.
+
+   See also changes to the "Models" chapter of the documentation (in
+   the "Location-Aware Model Instances") section.
+
+0.7.0 (2009-04-11)
+==================
+
+Bug Fixes
+---------
+
+- Fix a bug in ``repoze.bfg.wsgi.HTTPException``: the content length
+  was returned as an int rather than as a string.
+ 
+- Add explicit dependencies on ``zope.deferredimport``,
+  ``zope.deprecation``, and ``zope.proxy`` for forward compatibility
+  reasons (``zope.component`` will stop relying on
+  ``zope.deferredimport`` soon and although we use it directly, it's
+  only a transitive dependency, and ''zope.deprecation`` and
+  ``zope.proxy`` are used directly even though they're only transitive
+  dependencies as well).
+
+- Using ``model_url`` or ``model_path`` against a broken model graph
+  (one with models that had a non-root model with a ``__name__`` of
+  ``None``) caused an inscrutable error to be thrown: ( if not
+  ``_must_quote[cachekey].search(s): TypeError: expected string or
+  buffer``).  Now URLs and paths generated against graphs that have
+  None names in intermediate nodes will replace the None with the
+  empty string, and, as a result, the error won't be raised.  Of
+  course the URL or path will still be bogus.
+
+Features
+--------
+
+- Make it possible to have ``testing.DummyTemplateRenderer`` return
+  some nondefault string representation.
+
+- Added a new ``anchor`` keyword argument to ``model_url``.  If 
+  ``anchor`` is present, its string representation will be used 
+  as a named anchor in the generated URL (e.g. if ``anchor`` is 
+  passed as ``foo`` and the model URL is 
+  ``http://example.com/model/url``, the generated URL will be 
+  ``http://example.com/model/url#foo``).
+
+Backwards Incompatibilities
+---------------------------
+
+- The default request charset encoding is now ``utf-8``.  As a result,
+  the request machinery will attempt to decode values from the utf-8
+  encoding to Unicode automatically when they are obtained via
+  ``request.params``, ``request.GET``, and ``request.POST``.  The
+  previous behavior of BFG was to return a bytestring when a value was
+  accessed in this manner.  This change will break form handling code
+  in apps that rely on values from those APIs being considered
+  bytestrings.  If you are manually decoding values from form
+  submissions in your application, you'll either need to change the
+  code that does that to expect Unicode values from
+  ``request.params``, ``request.GET`` and ``request.POST``, or you'll
+  need to explicitly reenable the previous behavior.  To reenable the
+  previous behavior, add the following to your application's
+  ``configure.zcml``::
+
+    <subscriber for="repoze.bfg.interfaces.INewRequest"
+                handler="repoze.bfg.request.make_request_ascii"/>
+
+  See also the documentation in the "Views" chapter of the BFG docs
+  entitled "Using Views to Handle Form Submissions (Unicode and
+  Character Set Issues)".
+
+Documentation
+-------------
+
+- Add a section to the narrative Views chapter entitled "Using Views
+  to Handle Form Submissions (Unicode and Character Set Issues)"
+  explaining implicit decoding of form data values.
+
+0.6.9 (2009-02-16)
+==================
+
+Bug Fixes
+---------
+
+- lru cache was unstable under concurrency (big surprise!) when it
+  tried to redelete a key in the cache that had already been deleted.
+  Symptom: line 64 in put:del data[oldkey]:KeyError: '/some/path'.
+  Now we just ignore the key error if we can't delete the key (it has
+  already been deleted).
+
+- Empty location names in model paths when generating a URL using
+  ``repoze.bfg.model_url`` based on a model obtained via traversal are
+  no longer ignored in the generated URL.  This means that if a
+  non-root model object has a ``__name__`` of ``''``, the URL will
+  reflect it (e.g. ``model_url`` will generate ``http://foo/bar//baz``
+  if an object with the ``__name__`` of ``''`` is a child of bar and
+  the parent of baz).  URLs generated with empty path segments are,
+  however, still irresolveable by the model graph traverser on request
+  ingress (the traverser strips empty path segment names).
+
+Features
+--------
+
+- Microspeedups of ``repoze.bfg.traversal.model_path``,
+  ``repoze.bfg.traversal.model_path_tuple``,
+  ``repoze.bfg.traversal.quote_path_segment``, and
+  ``repoze.bfg.url.urlencode``.
+
+- add zip_safe = false to setup.cfg.
+
+Documentation
+-------------
+
+- Add a note to the ``repoze.bfg.traversal.quote_path_segment`` API
+  docs about caching of computed values.
+
+Implementation Changes
+----------------------
+
+- Simplification of
+  ``repoze.bfg.traversal.TraversalContextURL.__call__`` (it now uses
+  ``repoze.bfg.traversal.model_path`` instead of rolling its own
+  path-generation).
+
+0.6.8 (2009-02-05)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``repoze.bfg.traversal.model_path`` API now returns a *quoted*
+  string rather than a string represented by series of unquoted
+  elements joined via ``/`` characters.  Previously it returned a
+  string or unicode object representing the model path, with each
+  segment name in the path joined together via ``/`` characters,
+  e.g. ``/foo /bar``.  Now it returns a string, where each segment is
+  a UTF-8 encoded and URL-quoted element e.g. ``/foo%20/bar``.  This
+  change was (as discussed briefly on the repoze-dev maillist)
+  necessary to accomodate model objects which themselves have
+  ``__name__`` attributes that contain the ``/`` character.
+
+  For people that have no models that have high-order Unicode
+  ``__name__`` attributes or ``__name__`` attributes with values that
+  require URL-quoting with in their model graphs, this won't cause any
+  issue.  However, if you have code that currently expects
+  ``model_path`` to return an unquoted string, or you have an existing
+  application with data generated via the old method, and you're too
+  lazy to change anything, you may wish replace the BFG-imported
+  ``model_path`` in your code with this function (this is the code of
+  the "old" ``model_path`` implementation)::
+
+        from repoze.bfg.location import lineage
+
+        def i_am_too_lazy_to_move_to_the_new_model_path(model, *elements):
+            rpath = []
+            for location in lineage(model):
+                if location.__name__:
+                    rpath.append(location.__name__)
+            path = '/' + '/'.join(reversed(rpath))
+            if elements:
+                suffix = '/'.join(elements)
+                path = '/'.join([path, suffix])
+            return path
+
+- The ``repoze.bfg.traversal.find_model`` API no longer implicitly
+  converts unicode representations of a full path passed to it as a
+  Unicode object into a UTF-8 string.  Callers should either use
+  prequoted path strings returned by
+  ``repoze.bfg.traversal.model_path``, or tuple values returned by the
+  result of ``repoze.bfg.traversal.model_path_tuple`` or they should
+  use the guidelines about passing a string ``path`` argument
+  described in the ``find_model`` API documentation.
+
+Bugfixes
+--------
+
+- Each argument contained in ``elements`` passed to
+  ``repoze.bfg.traversal.model_path`` will now have any ``/``
+  characters contained within quoted to ``%2F`` in the returned
+  string.  Previously, ``/`` characters in elements were left unquoted
+  (a bug).
+
+Features
+--------
+
+- A ``repoze.bfg.traversal.model_path_tuple`` API was added.  This API
+  is an alternative to ``model_path`` (which returns a string);
+  ``model_path_tuple`` returns a model path as a tuple (much like
+  Zope's ``getPhysicalPath``).
+
+- A ``repoze.bfg.traversal.quote_path_segment`` API was added.  This
+  API will quote an individual path segment (string or unicode
+  object).  See the ``repoze.bfg.traversal`` API documentation for
+  more information.
+
+- The ``repoze.bfg.traversal.find_model`` API now accepts "path
+  tuples" (see the above note regarding ``model_path_tuple``) as well
+  as string path representations (from
+  ``repoze.bfg.traversal.model_path``) as a ``path`` argument.
+
+- Add ` `renderer`` argument (defaulting to None) to
+  ``repoze.bfg.testing.registerDummyRenderer``.  This makes it
+  possible, for instance, to register a custom renderer that raises an
+  exception in a unit test.
+
+Implementation Changes
+----------------------
+
+- Moved _url_quote function back to ``repoze.bfg.traversal`` from
+  ``repoze.bfg.url``.  This is not an API.
+
+0.6.7 (2009-01-27)
+==================
+
+Features
+--------
+
+- The ``repoze.bfg.url.model_url`` API now works against contexts
+  derived from Routes URL dispatch (``Routes.util.url_for`` is called
+  under the hood).
+
+- "Virtual root" support for traversal-based applications has been
+  added.  Virtual root support is useful when you'd like to host some
+  model in a ``repoze.bfg`` model graph as an application under a
+  URL pathname that does not include the model path itself.  For more
+  information, see the (new) "Virtual Hosting" chapter in the
+  documentation.
+
+- A ``repoze.bfg.traversal.virtual_root`` API has been added.  When
+  called, it returns the virtual root object (or the physical root
+  object if no virtual root has been specified).
+
+Implementation Changes
+----------------------
+
+- ``repoze.bfg.traversal.RoutesModelTraverser`` has been moved to
+  ``repoze.bfg.urldispatch``.
+
+- ``model_url`` URL generation is now performed via an adapter lookup
+  based on the context and the request.
+
+- ZCML which registers two adapters for the ``IContextURL`` interface
+  has been added to the configure.zcml in ``repoze.bfg.includes``.
+
+0.6.6 (2009-01-26)
+==================
+
+Implementation Changes
+----------------------
+
+- There is an indirection in ``repoze.bfg.url.model_url`` now that
+  consults a utility to generate the base model url (without extra
+  elements or a query string).  Eventually this will service virtual
+  hosting; for now it's undocumented and should not be hooked.
+
+0.6.5 (2009-01-26)
+==================
+
+Features
+--------
+
+- You can now override the NotFound and Unauthorized responses that
+  ``repoze.bfg`` generates when a view cannot be found or cannot be
+  invoked due to lack of permission.  See the "ZCML Hooks" chapter in
+  the docs for more information.
+
+- Added Routes ZCML directive attribute explanations in documentation.
+
+- Added a ``traversal_path`` API to the traversal module; see the
+  "traversal" API chapter in the docs.  This was a function previously
+  known as ``split_path`` that was not an API but people were using it
+  anyway.  Unlike ``split_path``, it now returns a tuple instead of a
+  list (as its values are cached).
+
+Behavior Changes
+----------------
+
+- The ``repoze.bfg.view.render_view_to_response`` API will no longer
+  raise a ValueError if an object returned by a view function it calls
+  does not possess certain attributes (``headerlist``, ``app_iter``,
+  ``status``).  This API used to attempt to perform a check using the
+  ``is_response`` function in ``repoze.bfg.view``, and raised a
+  ``ValueError`` if the ``is_response`` check failed.  The
+  responsibility is now the caller's to ensure that the return value
+  from a view function is a "real" response.
+
+- WSGI environ dicts passed to ``repoze.bfg`` 's Router must now
+  contain a REQUEST_METHOD key/value; if they do not, a KeyError will
+  be raised (speed).  
+
+- It is no longer permissible to pass a "nested" list of principals to
+  ``repoze.bfg.ACLAuthorizer.permits`` (e.g. ``['fred', ['larry',
+  'bob']]``).  The principals list must be fully expanded.  This
+  feature was never documented, and was never an API, so it's not a
+  backwards incompatibility.
+
+- It is no longer permissible for a security ACE to contain a "nested"
+  list of permissions (e.g. ``(Allow, Everyone, ['read', ['view',
+  ['write', 'manage']]])`)`.  The list must instead be fully expanded
+  (e.g. ``(Allow, Everyone, ['read', 'view', 'write', 'manage])``).  This
+  feature was never documented, and was never an API, so it's not a
+  backwards incompatibility.
+
+- The ``repoze.bfg.urldispatch.RoutesRootFactory`` now injects the
+  ``wsgiorg.routing_args`` environment variable into the environ when
+  a route matches.  This is a tuple of ((), routing_args) where
+  routing_args is the value that comes back from the routes mapper
+  match (the "match dict").
+
+- The ``repoze.bfg.traversal.RoutesModelTraverser`` class now wants to
+  obtain the ``view_name`` and ``subpath`` from the
+  ``wsgiorgs.routing_args`` environment variable.  It falls back to
+  obtaining these from the context for backwards compatibility.
+
+Implementation Changes
+----------------------
+
+- Get rid of ``repoze.bfg.security.ACLAuthorizer``: the
+  ``ACLSecurityPolicy`` now does what it did inline.
+
+- Get rid of ``repoze.bfg.interfaces.NoAuthorizationInformation``
+  exception: it was used only by ``ACLAuthorizer``.
+
+- Use a homegrown NotFound error instead of ``webob.exc.HTTPNotFound``
+  (the latter is slow).
+
+- Use a homegrown Unauthorized error instead of
+  ``webob.exc.Unauthorized`` (the latter is slow).
+
+- the ``repoze.bfg.lru.lru_cached`` decorator now uses functools.wraps
+  in order to make documentation of LRU-cached functions possible.
+
+- Various speed micro-tweaks.
+
+Bug Fixes
+---------
+
+- ``repoze.bfg.testing.DummyModel`` did not have a ``get`` method;
+  it now does.
+
+0.6.4 (2009-01-23)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- The ``unicode_path_segments`` configuration variable and the
+  ``BFG_UNICODE_PATH_SEGMENTS`` configuration variable have been
+  removed.  Path segments are now always passed to model
+  ``__getitem__`` methods as unicode.  "True" has been the default for
+  this setting since 0.5.4, but changing this configuration setting to
+  false allowed you to go back to passing raw path element strings to
+  model ``__getitem__`` methods.  Removal of this knob services a
+  speed goal (we get about +80 req/s by removing the check), and it's
+  clearer just to always expect unicode path segments in model
+  ``__getitem__`` methods.
+
+Implementation Changes
+----------------------
+
+- ``repoze.bfg.traversal.split_path`` now also handles decoding
+  path segments to unicode (for speed, because its results are
+  cached).
+
+- ``repoze.bfg.traversal.step`` was made a method of the
+   ModelGraphTraverser.
+
+- Use "precooked" Request subclasses
+  (e.g. ``repoze.bfg.request.GETRequest``) that correspond to HTTP
+  request methods within ``router.py`` when constructing a request
+  object rather than using ``alsoProvides`` to attach the proper
+  interface to an unsubclassed ``webob.Request``.  This pattern is
+  purely an optimization (e.g. preventing calls to ``alsoProvides``
+  means the difference between 590 r/s and 690 r/s on a MacBook 2GHz).
+
+- Tease out an extra 4% performance boost by changing the Router;
+  instead of using imported ZCA APIs, use the same APIs directly
+  against the registry that is an attribute of the Router.
+
+- The registry used by BFG is now a subclass of
+  ``zope.component.registry.Components`` (defined as
+  ``repoze.bfg.registry.Registry``); it has a ``notify`` method, a
+  ``registerSubscriptionAdapter`` and a ``registerHandler`` method.
+  If no subscribers are registered via ``registerHandler`` or
+  ``registerSubscriptionAdapter``, ``notify`` is a noop for speed.
+
+- The Allowed and Denied classes in ``repoze.bfg.security`` now are
+  lazier about constructing the representation of a reason message for
+  speed; ``repoze.bfg.view_execution_permitted`` takes advantage of
+  this.
+
+- The ``is_response`` check was sped up by about half at the expense
+  of making its code slightly uglier.
+
+New Modules
+-----------
+
+- ``repoze.bfg.lru`` implements an LRU cache class and a decorator for
+  internal use.
+
+0.6.3 (2009-01-19)
+==================
+
+Bug Fixes
+---------
+
+- Readd ``root_policy`` attribute on Router object (as a property
+  which returns the IRootFactory utility).  It was inadvertently
+  removed in 0.6.2.  Code in the wild depended upon its presence
+  (esp. scripts and "debug" helpers).
+
+Features
+--------
+
+- URL-dispatch has been overhauled: it is no longer necessary to
+  manually create a RoutesMapper in your application's entry point
+  callable in order to use URL-dispatch (aka `Routes
+  <http://routes.groovie.org>`_).  A new ``route`` directive has been
+  added to the available list of ZCML directives.  Each ``route``
+  directive inserted into your application's ``configure.zcml``
+  establishes a Routes mapper connection.  If any ``route``
+  declarations are made via ZCML within a particular application, the
+  ``get_root`` callable passed in to ``repoze.bfg.router.make_app``
+  will automatically be wrapped in the equivalent of a RoutesMapper.
+  Additionally, the new ``route`` directive allows the specification
+  of a ``context_interfaces`` attribute for a route, this will be used
+  to tag the manufactured routes context with specific interfaces when
+  a route specifying a ``context_interfaces`` attribute is matched.
+
+- A new interface ``repoze.bfg.interfaces.IContextNotFound`` was
+  added.  This interface is attached to a "dummy" context generated
+  when Routes cannot find a match and there is no "fallback" get_root
+  callable that uses traversal.
+
+- The ``bfg_starter`` and ``bfg_zodb`` "paster create" templates now
+  contain images and CSS which are displayed when the default page is
+  displayed after initial project generation.
+
+- Allow the ``repoze.bfg.view.static`` helper to be passed a relative
+  ``root_path`` name; it will be considered relative to the file in
+  which it was called.
+
+- The functionality of ``repoze.bfg.convention`` has been merged into
+  the core.  Applications which make use of ``repoze.bfg.convention``
+  will continue to work indefinitely, but it is recommended that apps
+  stop depending upon it.  To do so, substitute imports of
+  ``repoze.bfg.convention.bfg_view`` with imports of
+  ``repoze.bfg.view.bfg_view``, and change the stanza in ZCML from
+  ``<convention package=".">`` to ``<scan package=".">``.  As a result
+  of the merge, bfg has grown a new dependency: ``martian``.
+
+- View functions which use the pushpage decorator are now pickleable
+  (meaning their use won't prevent a ``configure.zcml.cache`` file
+  from being written to disk).
+
+- Instead of invariably using ``webob.Request`` as the "request
+  factory" (e.g. in the ``Router`` class) and ``webob.Response`` and
+  the "response factory" (e.g. in ``render_template_to_response``),
+  allow both to be overridden via a ZCML utility hook.  See the "Using
+  ZCML Hooks" chapter of the documentation for more information.
+
+Deprecations
+------------
+
+- The class ``repoze.bfg.urldispatch.RoutesContext`` has been renamed
+  to ``repoze.bfg.urldispatch.DefaultRoutesContext``.  The class
+  should be imported by the new name as necessary (although in reality
+  it probably shouldn't be imported from anywhere except internally
+  within BFG, as it's not part of the API).
+
+Implementation Changes
+----------------------
+
+- The ``repoze.bfg.wsgi.wsgiapp`` decorator now uses
+  ``webob.Request.get_response`` to do its work rather than relying on
+  homegrown WSGI code.
+
+- The ``repoze.bfg.view.static`` helper now uses
+  ``webob.Request.get_response`` to do its work rather than relying on
+  homegrown WSGI code.
+
+- The ``repoze.bfg.urldispatch.RoutesModelTraverser`` class has been
+  moved to ``repoze.bfg.traversal.RoutesModelTraverser``.
+
+- The ``repoze.bfg.registry.makeRegistry`` function was renamed to
+  ``repoze.bfg.registry.populateRegistry`` and now accepts a
+  ``registry`` argument (which should be an instance of
+  ``zope.component.registry.Components``).
+
+Documentation Additions
+-----------------------
+
+- Updated narrative urldispatch chapter with changes required by
+  ``<route..>`` ZCML directive.
+
+- Add a section on "Using BFG Security With URL Dispatch" into the
+  urldispatch chapter of the documentation.
+
+- Better documentation of security policy implementations that ship
+  with repoze.bfg.
+
+- Added a "Using ZPT Macros in repoze.bfg" section to the narrative
+  templating chapter.
+
+0.6.2 (2009-01-13)
+==================
+
+Features
+--------
+
+- Tests can be run with coverage output if you've got ``nose``
+  installed in the interpreter which you use to run tests.  Using an
+  interpreter with ``nose`` installed, do ``python setup.py
+  nosetests`` within a checkout of the ``repoze.bfg`` package to see
+  test coverage output.
+
+- Added a ``post`` argument to the ``repoze.bfg.testing:DummyRequest``
+  constructor.
+  
+- Added ``__len__`` and ``__nonzero__`` to ``repoze.bfg.testing:DummyModel``.
+
+- The ``repoze.bfg.registry.get_options`` callable (now renamed to
+  ``repoze.bfg.setings.get_options``) used to return only
+  framework-specific keys and values in the dictionary it returned.
+  It now returns all the keys and values in the dictionary it is
+  passed *plus* any framework-specific settings culled from the
+  environment.  As a side effect, all PasteDeploy application-specific
+  config file settings are made available as attributes of the
+  ``ISettings`` utility from within BFG.
+
+- Renamed the existing BFG paster template to ``bfg_starter``.  Added
+  another template (``bfg_zodb``) showing default ZODB setup using
+  ``repoze.zodbconn``.
+
+- Add a method named ``assert_`` to the DummyTemplateRenderer.  This
+  method accepts keyword arguments.  Each key/value pair in the
+  keyword arguments causes an assertion to be made that the renderer
+  received this key with a value equal to the asserted value.
+
+- Projects generated by the paster templates now use the
+  ``DummyTemplateRenderer.assert_`` method in their view tests.
+
+- Make the (internal) thread local registry manager maintain a stack
+  of registries in order to make it possible to call one BFG
+  application from inside another.
+
+- An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is
+  attached to each request object on ingress.  The HTTP-verb-related
+  interfaces are defined in ``repoze.bfg.interfaces`` and are
+  ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``,
+  ``IDELETERequest`` and ``IHEADRequest``.  These interfaces can be
+  specified as the ``request_type`` attribute of a bfg view
+  declaration.  A view naming a specific HTTP-verb-matching interface
+  will be found only if the view is defined with a request_type that
+  matches the HTTP verb in the incoming request.  The more general
+  ``IRequest`` interface can be used as the request_type to catch all
+  requests (and this is indeed the default).  All requests implement
+  ``IRequest``. The HTTP-verb-matching idea was pioneered by
+  `repoze.bfg.restrequest
+  <http://pypi.python.org/pypi/repoze.bfg.restrequest/1.0.1>`_ . That
+  package is no longer required, but still functions fine.
+
+Bug Fixes
+---------
+
+- Fix a bug where the Paste configuration's ``unicode_path_segments``
+  (and os.environ's ``BFG_UNICODE_PATH_SEGMENTS``) may have been
+  defaulting to false in some circumstances.  It now always defaults
+  to true, matching the documentation and intent.
+
+- The ``repoze.bfg.traversal.find_model`` API did not work properly
+  when passed a ``path`` argument which was unicode and contained
+  high-order bytes when the ``unicode_path_segments`` or
+  ``BFG_UNICODE_PATH_SEGMENTS`` configuration variables were "true".
+
+- A new module was added: ``repoze.bfg.settings``.  This contains
+  deployment-settings-related code.
+
+Implementation Changes
+----------------------
+
+- The ``make_app`` callable within ``repoze.bfg.router`` now registers
+  the ``root_policy`` argument as a utility (unnamed, using the new
+  ``repoze.bfg.interfaces.IRootFactory`` as a provides interface)
+  rather than passing it as the first argument to the
+  ``repoze.bfg.router.Router`` class.  As a result, the
+  ``repoze.bfg.router.Router`` router class only accepts a single
+  argument: ``registry``.  The ``repoze.bfg.router.Router`` class
+  retrieves the root policy via a utility lookup now.  The
+  ``repoze.bfg.router.make_app`` API also now performs some important
+  application registrations that were previously handled inside
+  ``repoze.bfg.registry.makeRegistry``.
+
+New Modules
+-----------
+
+- A ``repoze.bfg.settings`` module was added.  It contains code
+  related to deployment settings.  Most of the code it contains was
+  moved to it from the ``repoze.bfg.registry`` module.
+
+Behavior Changes
+----------------
+
+- The ``repoze.bfg.settings.Settings`` class (an instance of which is
+  registered as a utility providing
+  ``repoze.bfg.interfaces.ISettings`` when any application is started)
+  now automatically calls ``repoze.bfg.settings.get_options`` on the
+  options passed to its constructor.  This means that usage of
+  ``get_options`` within an application's ``make_app`` function is no
+  longer required (the "raw" ``options`` dict or None may be passed).
+
+- Remove old cold which attempts to recover from trying to unpickle a
+  ``z3c.pt`` template; Chameleon has been the templating engine for a
+  good long time now.  Running repoze.bfg against a sandbox that has
+  pickled ``z3c.pt`` templates it will now just fail with an
+  unpickling error, but can be fixed by deleting the template cache
+  files.
+
+Deprecations
+------------
+
+- Moved the ``repoze.bfg.registry.Settings`` class.  This has been
+  moved to ``repoze.bfg.settings.Settings``. A deprecation warning is
+  issued when it is imported from the older location.
+
+- Moved the ``repoze.bfg.registry.get_options`` function This has been
+  moved to ``repoze.bfg.settings.get_options``.  A deprecation warning
+  is issued when it is imported from the older location.
+
+- The ``repoze.bfg.interfaces.IRootPolicy`` interface was renamed
+  within the interfaces package.  It has been renamed to
+  ``IRootFactory``.  A deprecation warning is issued when it is
+  imported from the older location.
+
+0.6.1 (2009-01-06)
+==================
+
+New Modules
+-----------
+
+- A new module ``repoze.bfg.url`` has been added.  It contains the
+  ``model_url`` API (moved from ``repoze.bfg.traversal``) and an
+  implementation of ``urlencode`` (like Python's
+  ``urllib.urlencode``) which can handle Unicode keys and values in
+  parameters to the ``query`` argument.
+
+Deprecations
+------------
+
+- The ``model_url`` function has been moved from
+  ``repoze.bfg.traversal`` into ``repoze.bfg.url``.  It can still
+  be imported from ``repoze.bfg.traversal`` but an import from
+  ``repoze.bfg.traversal`` will emit a DeprecationWarning.
+
+Features
+--------
+
+- A ``static`` helper class was added to the ``repoze.bfg.views``
+  module.  Instances of this class are willing to act as BFG views
+  which return static resources using files on disk.  See the
+  ``repoze.bfg.view`` docs for more info.
+
+- The ``repoze.bfg.url.model_url`` API (nee'
+  ``repoze.bfg.traversal.model_url``) now accepts and honors a
+  keyword argument named ``query``.  The value of this argument
+  will be used to compose a query string, which will be attached to
+  the generated URL before it is returned.  See the API docs (in
+  the docs directory or `on the web
+  <http://static.repoze.org/bfgdocs>`_) for more information.
+
+0.6 (2008-12-26)
+================
+
+Backwards Incompatibilities
+---------------------------
+
+- Rather than prepare the "stock" implementations of the ZCML directives
+  from the ``zope.configuration`` package for use under ``repoze.bfg``,
+  ``repoze.bfg`` now makes available the implementations of directives
+  from the ``repoze.zcml`` package (see http://static.repoze.org/zcmldocs).
+  As a result, the ``repoze.bfg`` package now depends on the
+  ``repoze.zcml`` package, and no longer depends directly on the
+  ``zope.component``, ``zope.configuration``, ``zope.interface``, or
+  ``zope.proxy`` packages.
+
+  The primary reason for this change is to enable us to eventually reduce
+  the number of inappropriate ``repoze.bfg`` Zope package dependencies,
+  as well as to shed features of dependent package directives that don't
+  make sense for ``repoze.bfg``.
+
+  Note that currently the set of requirements necessary to use bfg has not
+  changed.  This is due to inappropriate Zope package requirements in
+  ``chameleon.zpt``, which will hopefully be remedied soon. NOTE: in
+  lemonade index a 1.0b8-repozezcml0 package exists which does away with
+  these requirements.
+
+- BFG applications written prior to this release which expect the "stock"
+  ``zope.component`` ZCML directive implementations (e.g. ``adapter``,
+  ``subscriber``, or ``utility``) to function now must either 1) include
+  the ``meta.zcml`` file from ``zope.component`` manually (e.g. ``<include
+  package="zope.component" file="meta.zcml">``) and include the
+  ``zope.security`` package as an ``install_requires`` dependency or 2)
+  change the ZCML in their applications to use the declarations from
+  `repoze.zcml <http://static.repoze.org/zcmldocs/>`_ instead of the stock
+  declarations.  ``repoze.zcml`` only makes available the ``adapter``,
+  ``subscriber`` and ``utility`` directives.
+
+  In short, if you've got an existing BFG application, after this
+  update, if your application won't start due to an import error for
+  "zope.security", the fastest way to get it working again is to add
+  ``zope.security`` to the "install_requires" of your BFG
+  application's ``setup.py``, then add the following ZCML anywhere
+  in your application's ``configure.zcml``::
+
+   <include package="zope.component" file="meta.zcml">
+
+  Then re-``setup.py develop`` or reinstall your application.
+
+- The ``http://namespaces.repoze.org/bfg`` XML namespace is now the default
+  XML namespace in ZCML for paster-generated applications.  The docs have
+  been updated to reflect this.
+
+- The copies of BFG's ``meta.zcml`` and ``configure.zcml`` were removed
+  from the root of the ``repoze.bfg`` package.  In 0.3.6, a new package
+  named ``repoze.bfg.includes`` was added, which contains the "correct"
+  copies of these ZCML files; the ones that were removed were for backwards
+  compatibility purposes.
+
+- The BFG ``view`` ZCML directive no longer calls
+  ``zope.component.interface.provideInterface`` for the ``for`` interface.
+  We don't support ``provideInterface`` in BFG because it mutates the
+  global registry.
+
+Other
+-----
+
+- The minimum requirement for ``chameleon.core`` is now 1.0b13.  The
+  minimum requirement for ``chameleon.zpt`` is now 1.0b8.  The minimum
+  requirement for ``chameleon.genshi`` is now 1.0b2.
+
+- Updated paster template "ez_setup.py" to one that requires setuptools
+  0.6c9.
+
+- Turn ``view_execution_permitted`` from the ``repoze.bfg.view`` module
+  into a documented API.
+
+- Doc cleanups.
+
+- Documented how to create a view capable of serving static resources.
+
+0.5.6 (2008-12-18)
+==================
+
+- Speed up ``traversal.model_url`` execution by using a custom url quoting
+  function instead of Python's ``urllib.quote``, by caching URL path
+  segment quoting and encoding results, by disusing Python's
+  ``urlparse.urljoin`` in favor of a simple string concatenation, and by
+  using ``ob.__class__ is unicode`` rather than ``isinstance(ob, unicode)``
+  in one strategic place.
+
+0.5.5 (2008-12-17)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- In the past, during traversal, the ModelGraphTraverser (the default
+  traverser) always passed each URL path segment to any ``__getitem__``
+  method of a model object as a byte string (a ``str`` object).  Now, by
+  default the ModelGraphTraverser attempts to decode the path segment to
+  Unicode (a ``unicode`` object) using the UTF-8 encoding before passing it
+  to the ``__getitem__`` method of a model object.  This makes it possible
+  for model objects to be dumber in ``__getitem__`` when trying to resolve
+  a subobject, as model objects themselves no longer need to try to divine
+  whether or not to try to decode the path segment passed by the
+  traverser.
+
+  Note that since 0.5.4, URLs generated by repoze.bfg's ``model_url`` API
+  will contain UTF-8 encoded path segments as necessary, so any URL
+  generated by BFG itself will be decodeable by the traverser.  If another
+  application generates URLs to a BFG application, to be resolved
+  successully, it should generate the URL with UTF-8 encoded path segments
+  to be successfully resolved.  The decoder is not at all magical: if a
+  non-UTF-8-decodeable path segment (e.g. one encoded using UTF-16 or some
+  other insanity) is passed in the URL, BFG will raise a ``TypeError`` with
+  a message indicating it could not decode the path segment.
+
+  To turn on the older behavior, where path segments were not decoded to
+  Unicode before being passed to model object ``__getitem__`` by the
+  traverser, and were passed as a raw byte string, set the
+  ``unicode_path_segments`` configuration setting to a false value in your
+  BFG application's section of the paste .ini file, for example::
+
+    unicode_path_segments = False
+
+  Or start the application using the ``BFG_UNICODE_PATH_SEGMENT`` envvar
+  set to a false value::
+
+    BFG_UNICODE_PATH_SEGMENTS=0
+
+0.5.4 (2008-12-13)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- URL-quote "extra" element names passed in as ``**elements`` to the
+  ``traversal.model_url`` API.  If any of these names is a Unicode string,
+  encode it to UTF-8 before URL-quoting.  This is a slight backwards
+  incompatibility that will impact you if you were already UTF-8 encoding
+  or URL-quoting the values you passed in as ``elements`` to this API.
+
+Bugfixes
+--------
+
+- UTF-8 encode each segment in the model path used to generate a URL before
+  url-quoting it within the ``traversal.model_url`` API.  This is a bugfix,
+  as Unicode cannot always be successfully URL-quoted.
+
+Features
+--------
+
+- Make it possible to run unit tests using a buildout-generated Python
+  "interpreter".  
+
+- Add ``request.root`` to ``router.Router`` in order to have easy access to
+  the application root.
+
+0.5.3 (2008-12-07)
+==================
+
+- Remove the ``ITestingTemplateRenderer`` interface.  When
+  ``testing.registerDummyRenderer`` is used, it instead registers a dummy
+  implementation using ``ITemplateRenderer`` interface, which is checked
+  for when the built-in templating facilities do rendering.  This change
+  also allows developers to make explcit named utility registrations in
+  the ZCML registry against ``ITemplateRenderer``; these will be found
+  before any on-disk template is looked up.
+
+0.5.2 (2008-12-05)
+==================
+
+- The component registration handler for views (functions or class
+  instances) now observes component adaptation annotations (see
+  ``zope.component.adaptedBy``) and uses them before the fallback values
+  for ``for_`` and ``request_type``. This change does not affect existing
+  code insomuch as the code does not rely on these defaults when an
+  annotation is set on the view (unlikely).  This means that for a
+  new-style class you can do ``zope.component.adapts(ISomeContext,
+  ISomeRequest)`` at class scope or at module scope as a decorator to a
+  bfg view function you can do ``@zope.component.adapter(ISomeContext,
+  ISomeRequest)``.  This differs from r.bfg.convention inasmuch as you
+  still need to put something in ZCML for the registrations to get done;
+  it's only the defaults that will change if these declarations exist.
+
+- Strip all slashes from end and beginning of path in clean_path within
+  traversal machinery.
+
+0.5.1 (2008-11-25)
+==================
+
+- Add ``keys``, ``items``, and ``values`` methods to
+  ``testing.DummyModel``.
+
+- Add __delitem__ method to ``testing.DummyModel``.
+
+0.5.0 (2008-11-18)
+==================
+
+- Fix ModelGraphTraverser; don't try to change the ``__name__`` or
+  ``__parent__`` of an object that claims it implements ILocation during
+  traversal even if the ``__name__`` or ``__parent__`` of the object
+  traversed does not match the name used in the traversal step or the or
+  the traversal parent .  Rationale: it was insane to do so. This bug was
+  only found due to a misconfiguration in an application that mistakenly
+  had intermediate persistent non-ILocation objects; traversal was causing
+  a persistent write on every request under this setup.
+
+- ``repoze.bfg.location.locate`` now unconditionally sets ``__name__`` and
+  ``__parent__`` on objects which provide ILocation (it previously only set
+  them conditionally if they didn't match attributes already present on the
+  object via equality).
+
+0.4.9 (2008-11-17)
+==================
+
+- Add chameleon text template API (chameleon ${name} renderings where the
+  template does not need to be wrapped in any containing XML).
+
+- Change docs to explain install in terms of a virtualenv
+  (unconditionally).
+
+- Make pushpage decorator compatible with repoze.bfg.convention's
+  ``bfg_view`` decorator when they're stacked.
+
+- Add content_length attribute to testing.DummyRequest.
+
+- Change paster template ``tests.py`` to include a true unit test.  Retain
+  old test as an integration test.  Update documentation.
+
+- Document view registrations against classes and ``repoze.bfg.convention``
+  in context.
+
+- Change the default paster template to register its single view against a
+  class rather than an interface.
+
+- Document adding a request type interface to the request via a subscriber
+  function in the events narrative documentation.
+
+0.4.8 (2008-11-12)
+==================
+
+Backwards Incompatibilities
+---------------------------
+
+- ``repoze.bfg.traversal.model_url`` now always appends a slash to all
+  generated URLs unless further elements are passed in as the third and
+  following arguments.  Rationale: views often use ``model_url`` without
+  the third-and-following arguments in order to generate a URL for a model
+  in order to point at the default view of a model.  The URL that points to
+  the default view of the *root* model is technically ``http://mysite/`` as
+  opposed to ``http://mysite`` (browsers happen to ask for '/' implicitly
+  in the GET request).  Because URLs are never automatically generated for
+  anything *except* models by ``model_url``, and because the root model is
+  not really special, we continue this pattern.  The impact of this change
+  is minimal (at most you will have too many slashes in your URL, which BFG
+  deals with gracefully anyway).
+
+0.4.7 (2008-11-11)
+==================
+
+Features
+--------
+
+- Allow ``testing.registerEventListener`` to be used with Zope 3 style
+  "object events" (subscribers accept more than a single event argument).
+  We extend the list with the arguments, rather than append.
+
+0.4.6 (2008-11-10)
+==================
+
+Bug Fixes
+---------
+
+- The ``model_path`` and ``model_url`` traversal APIs returned the wrong
+  value for the root object (e.g. ``model_path`` returned ``''`` for the
+  root object, while it should have been returning ``'/'``).
+
+0.4.5 (2008-11-09)
+==================
+
+Features
+--------
+
+- Added a ``clone`` method and a ``__contains__`` method to the DummyModel
+  testing object.
+
+- Allow DummyModel objects to receive extra keyword arguments, which will
+  be attached as attributes.
+
+- The DummyTemplateRenderer now returns ``self`` as its implementation.
+
+0.4.4 (2008-11-08)
+==================
+
+Features
+--------
+
+- Added a ``repoze.bfg.testing`` module to attempt to make it slightly
+  easier to write unittest-based automated tests of BFG applications.
+  Information about this module is in the documentation.
+
+- The default template renderer now supports testing better by looking for
+  ``ITestingTemplateRenderer`` using a relative pathname.  This is exposed
+  indirectly through the API named ``registerTemplateRenderer`` in
+  ``repoze.bfg.testing``.
+
+Deprecations
+------------
+
+- The names ``repoze.bfg.interfaces.ITemplate`` ,
+  ``repoze.bfg.interfaces.ITemplateFactory`` and
+  ``repoze.bfg.interfaces.INodeTemplate`` have been deprecated.  These
+  should now be imported as ``repoze.bfg.interfaces.ITemplateRenderer`` and
+  ``repoze.bfg.interfaces.ITemplateRendererFactory``, and
+  ``INodeTemplateRenderer`` respectively.
+
+- The name ``repoze.bfg.chameleon_zpt.ZPTTemplateFactory`` is deprecated.
+  Use ``repoze.bfg.chameleon_zpt.ZPTTemplateRenderer``.
+
+- The name ``repoze.bfg.chameleon_genshi.GenshiTemplateFactory`` is
+  deprecated.  Use ``repoze.bfg.chameleon_genshi.GenshiTemplateRenderer``.
+
+- The name ``repoze.bfg.xslt.XSLTemplateFactory`` is deprecated.  Use
+  ``repoze.bfg.xslt.XSLTemplateRenderer``.
+
+0.4.3 (2008-11-02)
+==================
+
+Bug Fixes
+---------
+
+- Not passing the result of "get_options" as the second argument of
+  make_app could cause attribute errors when attempting to look up settings
+  against the ISettings object (internal).  Fixed by giving the Settings
+  objects defaults for ``debug_authorization`` and ``debug_notfound``.
+
+- Return an instance of ``Allowed`` (rather than ``True``) from
+  ``has_permission`` when no security policy is in use.
+
+- Fix bug where default deny in authorization check would throw a TypeError
+  (use ``ACLDenied`` instead of ``Denied``).
+
+0.4.2 (2008-11-02)
+==================
+
+Features
+--------
+
+- Expose a single ILogger named "repoze.bfg.debug" as a utility; this
+  logger is registered unconditionally and is used by the authorization
+  debug machinery.  Applications may also make use of it as necessary
+  rather than inventing their own logger, for convenience.
+
+- The ``BFG_DEBUG_AUTHORIZATION`` envvar and the ``debug_authorization``
+  config file value now only imply debugging of view-invoked security
+  checks.  Previously, information was printed for every call to
+  ``has_permission`` as well, which made output confusing.  To debug
+  ``has_permission`` checks and other manual permission checks, use the
+  debugger and print statements in your own code.
+
+- Authorization debugging info is now only present in the HTTP response
+  body oif ``debug_authorization`` is true.
+
+- The format of authorization debug messages was improved.
+
+- A new ``BFG_DEBUG_NOTFOUND`` envvar was added and a symmetric
+  ``debug_notfound`` config file value was added.  When either is true, and
+  a NotFound response is returned by the BFG router (because a view could
+  not be found), debugging information is printed to stderr.  When this
+  value is set true, the body of HTTPNotFound responses will also contain
+  the same debugging information.
+
+- ``Allowed`` and ``Denied`` responses from the security machinery are now
+  specialized into two types: ACL types, and non-ACL types.  The
+  ACL-related responses are instances of ``repoze.bfg.security.ACLAllowed``
+  and ``repoze.bfg.security.ACLDenied``.  The non-ACL-related responses are
+  ``repoze.bfg.security.Allowed`` and ``repoze.bfg.security.Denied``.  The
+  allowed-type responses continue to evaluate equal to things that
+  themselves evaluate equal to the ``True`` boolean, while the denied-type
+  responses continue to evaluate equal to things that themselves evaluate
+  equal to the ``False`` boolean.  The only difference between the two
+  types is the information attached to them for debugging purposes.
+
+- Added a new ``BFG_DEBUG_ALL`` envvar and a symmetric ``debug_all`` config
+  file value.  When either is true, all other debug-related flags are set
+  true unconditionally (e.g. ``debug_notfound`` and
+  ``debug_authorization``).
+
+Documentation
+-------------
+
+- Added info about debug flag changes.
+
+- Added a section to the security chapter named "Debugging Imperative
+  Authorization Failures" (for e.g. ``has_permssion``).
+
+Bug Fixes
+---------
+
+- Change default paster template generator to use ``Paste#http`` server
+  rather than ``PasteScript#cherrpy`` server.  The cherrypy server has a
+  security risk in it when ``REMOTE_USER`` is trusted by the downstream
+  application.
+
+0.4.1 (2008-10-28)
+==================
+
+Bug Fixes
+---------
+
+- If the ``render_view_to_response`` function was called, if the view was
+  found and called, but it returned something that did not implement
+  IResponse, the error would pass by unflagged.  This was noticed when I
+  created a view function that essentially returned None, but received a
+  NotFound error rather than a ValueError when the view was rendered.  This
+  was fixed.
+
+0.4.0 (2008-10-03)
+==================
+
+Docs 
+----
+
+- An "Environment and Configuration" chapter was added to the narrative 
+  portion of the documentation.
+
+Features
+--------
+
+- Ensure bfg doesn't generate warnings when running under Python
+  2.6.
+
+- The environment variable ``BFG_RELOAD_TEMPLATES`` is now available
+  (serves the same purpose as ``reload_templates`` in the config file).
+
+- A new configuration file option ``debug_authorization`` was added.
+  This turns on printing of security authorization debug statements
+  to ``sys.stderr``.  The ``BFG_DEBUG_AUTHORIZATION`` environment
+  variable was also added; this performs the same duty.
+
+Bug Fixes
+---------
+
+- The environment variable ``BFG_SECURITY_DEBUG`` did not always work.
+  It has been renamed to ``BFG_DEBUG_AUTHORIZATION`` and fixed.
+
+Deprecations
+------------
+
+- A deprecation warning is now issued when old API names from the
+  ``repoze.bfg.templates`` module are imported.
+
+Backwards incompatibilities
+---------------------------
+
+- The ``BFG_SECURITY_DEBUG`` environment variable was renamed to
+  ``BFG_DEBUG_AUTHORIZATION``.
+
+0.3.9 (2008-08-27)
+==================
+
+Features
+--------
+
+- A ``repoze.bfg.location`` API module was added.
+
+Backwards incompatibilities
+---------------------------
+
+- Applications must now use the ``repoze.bfg.interfaces.ILocation``
+  interface rather than ``zope.location.interfaces.ILocation`` to
+  represent that a model object is "location-aware".  We've removed
+  a dependency on ``zope.location`` for cleanliness purposes: as
+  new versions of zope libraries are released which have improved
+  dependency information, getting rid of our dependence on
+  ``zope.location`` will prevent a newly installed repoze.bfg
+  application from requiring the ``zope.security``, egg, which not
+  truly used at all in a "stock" repoze.bfg setup.  These
+  dependencies are still required by the stack at this time; this
+  is purely a futureproofing move.
+
+  The security and model documentation for previous versions of
+  ``repoze.bfg`` recommended using the
+  ``zope.location.interfaces.ILocation`` interface to represent
+  that a model object is "location-aware".  This documentation has
+  been changed to reflect that this interface should now be
+  imported from ``repoze.bfg.interfaces.ILocation`` instead.
+
+0.3.8 (2008-08-26)
+==================
+
+Docs
+----
+
+- Documented URL dispatch better in narrative form.
+
+Bug fixes
+---------
+
+- Routes URL dispatch did not have access to the WSGI environment,
+  so conditions such as method=GET did not work.
+
+Features
+--------
+
+- Add ``principals_allowed_by_permission`` API to security module.
+
+- Replace ``z3c.pt`` support with support for ``chameleon.zpt``.
+  Chameleon is the new name for the package that used to be named
+  ``z3c.pt``.  NOTE: If you update a ``repoze.bfg`` SVN checkout
+  that you're using for development, you will need to run "setup.py
+  install" or "setup.py develop" again in order to obtain the
+  proper Chameleon packages.  ``z3c.pt`` is no longer supported by
+  ``repoze.bfg``.  All API functions that used to render ``z3c.pt``
+  templates will work fine with the new packages, and your
+  templates should render almost identically.
+
+- Add a ``repoze.bfg.chameleon_zpt`` module.  This module provides
+  Chameleon ZPT support.
+
+- Add a ``repoze.bfg.xslt`` module.  This module provides XSLT
+  support.
+
+- Add a ``repoze.bfg.chameleon_genshi`` module.  This provides
+  direct Genshi support, which did not exist previously.
+
+Deprecations
+------------
+
+- Importing API functions directly from ``repoze.bfg.template`` is
+  now deprecated.  The ``get_template``, ``render_template``,
+  ``render_template_to_response`` functions should now be imported
+  from ``repoze.chameleon_zpt``.  The ``render_transform``, and
+  ``render_transform_to_response`` functions should now be imported
+  from ``repoze.bfg.xslt``.  The ``repoze.bfg.template`` module
+  will remain around "forever" to support backwards compatibility.
+
+0.3.7 (2008-09-09)
+==================
+
+Features
+--------
+
+- Add compatibility with z3c.pt 1.0a7+ (z3c.pt became a namespace package).
+
+Bug fixes
+---------
+
+- ``repoze.bfg.traversal.find_model`` function did not function properly.
+
+0.3.6 (2008-09-04)
+==================
+
+Features
+--------
+
+- Add startup process docs.
+
+- Allow configuration cache to be bypassed by actions which include special
+  "uncacheable" discriminators (for actions that have variable results).
+
+Bug Fixes
+---------
+
+- Move core repoze.bfg ZCML into a ``repoze.bfg.includes`` package so we
+  can use repoze.bfg better as a namespace package.  Adjust the code
+  generator to use it.  We've left around the ``configure.zcml`` in the
+  repoze.bfg package directly so as not to break older apps.
+
+- When a zcml application registry cache was unpickled, and it contained a
+  reference to an object that no longer existed (such as a view), bfg would
+  not start properly.
+
+0.3.5 (2008-09-01)
+==================
+
+Features
+--------
+
+- Event notification is issued after application is created and configured
+  (``IWSGIApplicationCreatedEvent``).
+
+- New API module: ``repoze.bfg.view``.  This module contains the functions
+  named ``render_view_to_response``, ``render_view_to_iterable``,
+  ``render_view`` and ``is_response``, which are documented in the API
+  docs.  These features aid programmatic (non-server-driven) view
+  execution.
+
+0.3.4 (2008-08-28)
+==================
+
+Backwards incompatibilities
+---------------------------
+
+- Make ``repoze.bfg`` a namespace package so we can allow folks to create
+  subpackages (e.g. ``repoze.bfg.otherthing``) within separate eggs.  This
+  is a backwards incompatible change which makes it impossible to import
+  "make_app" and "get_options" from the ``repoze.bfg`` module directly.
+  This change will break all existing apps generated by the paster code
+  generator.  Instead, you need to import these functions as
+  ``repoze.bfg.router:make_app`` and ``repoze.bfg.registry:get_options``,
+  respectively.  Sorry folks, it has to be done now or never, and
+  definitely better now.
+
+Features
+--------
+
+- Add ``model_path`` API function to traversal module.
+
+Bugfixes
+
+- Normalize path returned by repoze.bfg.caller_path.
+
+0.3.3 (2008-08-23)
+==================
+
+- Fix generated test.py module to use project name rather than package
+  name.
+
+0.3.2 (2008-08-23)
+==================
+
+- Remove ``sampleapp`` sample application from bfg package itself.
+
+- Remove dependency on FormEncode (only needed by sampleapp).
+
+- Fix paster template generation so that case-sensitivity is preserved for
+  project vs. package name.
+
+- Depend on ``z3c.pt`` version 1.0a1 (which requires the ``[lxml]`` extra
+  currently).
+
+- Read and write a pickled ZCML actions list, stored as
+  ``configure.zcml.cache`` next to the applications's "normal"
+  configuration file.  A given bfg app will usually start faster if it's
+  able to read the pickle data.  It fails gracefully to reading the real
+  ZCML file if it cannot read the pickle.
+
+0.3.1 (2008-08-20)
+==================
+
+- Generated application differences: ``make_app`` entry point renamed to
+  ``app`` in order to have a different name than the bfg function of the
+  same name, to prevent confusion.
+
+- Add "options" processing to bfg's ``make_app`` to support runtime
+  options.  A new API function named ``get_options`` was added to the
+  registry module.  This function is typically used in an application's
+  ``app`` entry point.  The Paste config file section for the app can now
+  supply the ``reload_templates`` option, which, if true, will prevent the
+  need to restart the appserver in order for ``z3c.pt`` or XSLT template
+  changes to be detected.
+
+- Use only the module name in generated project's "test_suite" (run all
+  tests found in the package).
+
+- Default port for generated apps changed from 5432 to 6543 (Postgres
+  default port is 6543).
+
+0.3.0 (2008-08-16)
+==================
+
+- Add ``get_template`` API to template module.
+
+0.2.9 (2008-08-11)
+==================
+
+- 0.2.8 was "brown bag" release.  It didn't work at all.  Symptom:
+  ComponentLookupError when trying to render a page.
+
+0.2.8 (2008-08-11)
+==================
+
+- Add ``find_model`` and ``find_root`` traversal APIs.  In the process,
+  make ITraverser a uni-adapter (on context) rather than a multiadapter (on
+  context and request).
+
+0.2.7 (2008-08-05)
+==================
+
+- Add a ``request_type`` attribute to the available attributes of a
+  ``bfg:view`` configure.zcml element.  This attribute will have a value
+  which is a dotted Python path, pointing at an interface.  If the request
+  object implements this interface when the view lookup is performed, the
+  appropriate view will be called.  This is meant to allow for simple
+  "skinning" of sites based on request type.  An event subscriber should
+  attach the interface to the request on ingress to support skins.
+
+- Remove "template only" views.  These were just confusing and were never
+  documented.
+
+- Small url dispatch overhaul: the ``connect`` method of the
+  ``urldispatch.RoutesMapper`` object now accepts a keyword parameter named
+  ``context_factory``.  If this parameter is supplied, it must be a
+  callable which returns an instance.  This instance is used as the context
+  for the request when a route is matched.
+
+- The registration of a RoutesModelTraverser no longer needs to be
+  performed by the application; it's in the bfg ZCML now.
+
+0.2.6 (2008-07-31)
+==================
+
+- Add event sends for INewRequest and INewResponse.  See the events.rst
+  chapter in the documentation's ``api`` directory.
+
+0.2.5 (2008-07-28)
+==================
+
+- Add ``model_url`` API.
+
+0.2.4 (2008-07-27)
+==================
+
+- Added url-based dispatch.
+
+0.2.3 (2008-07-20)
+==================
+
+- Add API functions for authenticated_userid and effective_principals.
+
+0.2.2 (2008-07-20)
+==================
+
+- Add authenticated_userid and effective_principals API to security
+  policy.
+
+0.2.1 (2008-07-20)
+==================
+
+- Add find_interface API.
+
+0.2 (2008-07-19)
+================
+
+- Add wsgiapp decorator.
+
+- The concept of "view factories" was removed in favor of always calling a
+  view, which is a callable that returns a response directly (as opposed to
+  returning a view).  As a result, the ``factory`` attribute in the
+  bfg:view ZCML statement has been renamed to ``view``.  Various interface
+  names were changed also.
+
+- ``render_template`` and ``render_transform`` no longer return a Response
+  object.  Instead, these return strings.  The old behavior can be obtained
+  by using ``render_template_to_response`` and
+  ``render_transform_to_response``.
+
+- Added 'repoze.bfg.push:pushpage' decorator, which creates BFG views from
+  callables which take (context, request) and return a mapping of top-level
+  names.
+
+- Added ACL-based security.
+
+- Support for XSLT templates via a render_transform method
+
+0.1 (2008-07-08)
+================
+
+- Initial release.
+