[Python-checkins] r63328 - peps/trunk/pep-3108.txt

[alexandre.vassalotti]

Author: alexandre.vassalotti
Date: Thu May 15 23:19:55 2008
New Revision: 63328

Log:
Updated renaming process section.

Hopefully, this will help other developers to not make the same
mistakes I did.


Modified:
   peps/trunk/pep-3108.txt

Modified: peps/trunk/pep-3108.txt
==============================================================================
--- peps/trunk/pep-3108.txt	(original)
+++ peps/trunk/pep-3108.txt	Thu May 15 23:19:55 2008
@@ -988,12 +988,12 @@
 #. Create a stub module in ``Lib/lib-old``::
 
      from warnings import warnpy3k
-     warnpy3k("The XXX module has been renamed to XXX in Python 3.0",
+     warnpy3k("The OLDNAME module has been renamed to XXX in Python 3.0",
               stacklevel=2)
 
      from sys import modules
-     import XXX
-     modules[__name__] = XXX
+     import NEWNAME
+     modules[__name__] = NEWNAME
 
 #. Add a test to ``test_py3kwarn``.
 
@@ -1004,7 +1004,7 @@
    able to control commits easily).
 
 #. Update all import statements in the stdlib to use the new name
-   (use 2to3's ``fix_import`` fixer for the easiest solution).
+   (use 2to3's ``fix_imports`` fixer for the easiest solution).
 
 #. Rename the module in its own documentation.
 
@@ -1013,13 +1013,19 @@
 
 #. Commit the changes (this checkin should be allowed to propagate to py3k).
 
-#. Add a stub entry in the documentation for the old name which
-   lists the module as deprecated under that name and points to the
-   new name (see the module removal steps for what is required to do this).
-   
-#. In the module's documentation (under the new name), add a
-   ``versionchanged`` directive mentioning that the module was
-   renamed in Python 2.6.
+#. Add an index entry in the module documentation for the old name which
+   lists the module as deprecated under that name::
+
+     .. module:: OLDNAME
+        :synopsis: Old name for the NEWNAME module.
+
+#. In the module's documentation, add a note mentioning that the module was
+   renamed in Python 2.6::
+
+     .. note::
+        The :mod:`OLDNAME` module has been renamed to :mod:`NEWNAME` in
+        Python 3.0.  It is importable under both names in Python 2.6
+        and the rest of the 2.x series.
 
 #. Commit the changes (**block** in py3k).
 
@@ -1028,7 +1034,9 @@
 Python 3.0
 //////////
 
-#. Merge appropriate checkins from 2.6.
+#. Merge appropriate checkins from 2.6. Make that all changes were
+   applied correctly. Be aware, that ``svnmerge.py`` will not merge
+   changes made to previously renamed modules.
 
 #. Use ``svn move`` to rename the module.
 
@@ -1036,6 +1044,8 @@
 
 #. Add an entry in ``Misc/NEWS``.
 
+#. Run the test suite.
+
 #. Commit the changes.