diff -r f4f2139202c5 -r 4b311ce6624b Doc/packaging/index.rst
--- a/Doc/packaging/index.rst	Wed May 23 23:17:22 2012 +0200
+++ b/Doc/packaging/index.rst	Thu May 24 15:07:24 2012 +0200
@@ -18,6 +18,7 @@
    :numbered:
 
    tutorial
+   packagenames
    setupcfg
    introduction
    setupscript
diff -r f4f2139202c5 -r 4b311ce6624b Doc/packaging/packagenames.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Doc/packaging/packagenames.rst	Thu May 24 15:07:24 2012 +0200
@@ -0,0 +1,78 @@
+############################
+Package names and namespaces
+############################
+
+This document deals with package names and namespace packages. It provides
+conventions and guidelines to help you choose your package's name. 
+
+
+*****************
+Preliminary notes
+*****************
+
+Egg name VS package name
+========================
+
+Egg name is used by packaging utilities. It appears on Pypi.
+Package name is used in ``import`` statements.
+
+Technically, egg name and package name can be different.
+Best practice is to have them identical.
+
+New packages
+============
+
+New packages should follow both `Conventions`_ and `Guidelines`_ below.
+
+Existing packages
+=================
+
+There is no obligation for existing packages to be renamed.
+If you want to rename an existing package, see `How to rename an existing
+package`_.
+
+
+***********
+Conventions
+***********
+
+Rules that you SHOULD follow.
+
+Egg name and package name are identical
+=======================================
+
+Yes: egg name is "plone.recipe.command". Package name too.
+
+No: egg name is "django-sphinx". Package name is "sphinx".
+
+Valid characters for package names
+==================================
+
+Since `Egg name and package name are identical`_, PEP 8 applies to package
+names.
+
+
+**********
+Guidelines
+**********
+
+Advices that you CAN follow.
+
+
+*********************************
+How to rename an existing package
+*********************************
+
+* **DO NOT remove legacy package from Pypi.**
+* Create (copy/rename) a new package and publish it.
+* Edit legacy package:
+
+  * add dependency to new package.
+  * drop everything except packaging stuff.
+  * publish a new release.
+
+So, users of the legacy package will:
+
+* download legacy package, which is empty.
+* automatically download new package because as a dependency of the legacy
+  one.