- 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

1 files changed, 41 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index f7271114c..c41c1090b 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,44 @@
+Next release
+
+  Backwards Incompatbilities
+
+  - 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 (12/13/2008)
 
   Backwards Incompatibilities