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

[brett.cannon]

Author: brett.cannon
Date: Wed May  7 01:36:55 2008
New Revision: 62796

Log:
Thoroughly document the steps needed to handle a module slated for removal.


Modified:
   peps/trunk/pep-3108.txt

Modified: peps/trunk/pep-3108.txt
==============================================================================
--- peps/trunk/pep-3108.txt	(original)
+++ peps/trunk/pep-3108.txt	Wed May  7 01:36:55 2008
@@ -50,20 +50,6 @@
 denoted as "unique" then it is the last time the file was edited,
 period.
 
-The procedure to thoroughly remove a module is:
-
-#. Remove the module.
-#. Remove the tests.
-#. Edit ``Modules/Setup.dist`` and ``setup.py`` if needed.
-#. Remove the docs (if applicable).
-#. Run the regression test suite (using ``-uall``); watch out for
-   tests that are skipped because an import failed for the removed
-   module.
-
-If a deprecation warning is added to 2.6, it would be better to make
-all the changes to 2.6, merge the changes into the 3k branch, then
-perform the procedure above.  This will avoid some merge conflicts.
-
 
 Previously deprecated
 ---------------------
@@ -890,6 +876,51 @@
 ``warnings.warn3k()`` function.
 
 
+In Python 2.6
+/////////////
+
+#. Add the following code to the deprecated module (adjusting the
+   module name and the ``warnings`` import and needed)::
+
+     from warnings import warnpy3k
+     warnpy3k("the XXX module has been removed in Python 3.0",
+              stacklevel=2)
+     del warnpy3k
+
+#. Update the documentation. For modules with their own documentation
+   file, use the ``:deprecated:`` option for the ``module`` directive.
+   For modules simply listed in a file (e.g., ``undoc.rst``), use the
+   ``warning`` directive.
+
+#. Add the module to the module deletion test in ``test_py3kwarn``.
+
+#. Check in the change w/ appropriate ``Misc/NEWS`` entry (**block**
+   the checkin in ``py3k``!).
+
+#. Update this PEP noting that the 2.6 step is done.
+
+
+
+In Python 3.0
+/////////////
+
+#. Remove the module.
+
+#. Remove related tests.
+
+#. Remove all documentation.
+
+#. Edit ``Modules/Setup.dist`` and ``setup.py`` if needed.
+
+#. Run the regression test suite (using ``-uall``); watch out for
+   tests that are skipped because an import failed for the removed
+   module.
+
+#. Check in the change (with an appropriate ``Misc/NEWS`` entry).
+
+#. Update this PEP noting that the 3.0 step is done.
+
+
 Renaming of modules
 -------------------