diff -r 813e4817e573 -r 82f79e5e7f43 doc/packaging.txt
--- a/doc/packaging.txt	Fri Oct 10 10:07:08 2014 -0700
+++ b/doc/packaging.txt	Fri Oct 10 11:07:08 2014 -0700
@@ -185,5 +185,43 @@
     Once manifest validation has occurred, the package(s) is/are finally
     published to the workspace package repository.
 
+Renames
+
+    Renames in IPS are tricky.  We will use a case study to illustrate how
+    this needs to work.
+
+    All of the library/python-2/FOO modules that we had in Userland at the
+    time were renamed to library/python/FOO in s12_41.  This involved:
+    * changing the FMRI to drop the "-2"
+    * adding an optional dependency on the old name at the version and build
+      in which the rename occurred; this forces the rename
+      * depend type=optional fmri=library/python-2/FOO-$(PYV)@VERSION,BUILD
+      where FOO is the component name (e.g., "alembic", "amqp", etc.),
+      "$(PYV)" is that literal string, VERSION was the expanded value of
+      COMPONENT_VERSION from each component's Makefile (e.g., "0.6.0"
+      for alembic, "1.0.12" for amqp, etc.), and BUILD was set to
+      "5.12-5.12.0.0.0.41.0".  Note that BUILD needs to be set to
+      the value of the build you are integrating into.
+    * one or more new manifests (typically one for the versionless package,
+      plus one for each versioned instance of the package) with actions:
+      * set name=pkg.fmri value=pkg:/library/python-2/FOO@VERSION,BUILD
+      * set name=pkg.renamed value=true
+      * set name=org.opensolaris.consolidation value=$(CONSOLIDATION)
+      * depend fmri=library/python/FOO type=require
+      where FOO, VERSION and BUILD are all as above.
+
+    So far, not too bad.  This gets slightly more complicated when back-
+    porting in that BUILD needs to be set to the back-port build (e.g.,
+    "5.11-0.175.3.0.0.8.0", as was the case for tkinter-27) rather than
+    the S12 build.
+
+    If the component is at the same version as when the rename was done, then
+    that's it.  But if the component has since been upgraded, then care must
+    be taken to set VERSION in both places above to the value that it was in
+    s12_41 when the rename was originally done.  In particular, the latest
+    version of a package name in an earlier release branch must not be greater
+    than the latest version of that same package name in the newer release
+    branch.  Otherwise the audits from Release Engineering will complain and
+    our gatekeeper will make you do a follow-up push to fix this.
 
 # vi:set fdm=marker expandtab ts=4: