- 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.

1 files changed, 9 insertions, 0 deletions

diff --git a/docs/narr/models.rst b/docs/narr/models.rst
index 61e313830..9daa5668d 100644
--- a/docs/narr/models.rst
+++ b/docs/narr/models.rst
@@ -111,6 +111,15 @@ string.  For instance:
        __name__ = ''
        __parent__ = None
 
+.. note:: If your root model object has a ``__name__`` argument that
+  is not ``None`` or the empty string, URLs returned by the
+  ``repoze.bfg.url.model_url`` function and paths generated by the
+  ``repoze.bfg.traversal.model_path`` and
+  ``repoze.bfg.traversal.model_path_tuple`` APIs will be generated
+  improperly.  The value of ``__name__`` will be prepended to every
+  path and URL generated (as opposed to a single leading slash or
+  empty tuple element).
+
 A node returned from the root item's ``__getitem__`` method should
 have a ``__parent__`` attribute that is a reference to the root
 object, and its ``__name__`` attribute should match the name by which