Added "What Your Users Should Know" section, telling package developers

what information they should give to their users about dependencies,
network access, system packaging, and other common questions or
concerns.

--HG--
branch : setuptools
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/trunk/setuptools%4041717

1 files changed, 85 insertions, 2 deletions

diff --git a/setuptools.txt b/setuptools.txt
index f68244fa..f7a85c4e 100755
--- a/setuptools.txt
+++ b/setuptools.txt
@@ -960,10 +960,9 @@ There are several options to control the precise behavior of the ``develop``
 command; see the section on the `develop`_ command below for more details.
 
 
-Distributing a ``setuptools``-based package
+Distributing a ``setuptools``-based project
 ===========================================
 
-
 Using ``setuptools``...  Without bundling it!
 ---------------------------------------------
 
@@ -997,6 +996,88 @@ you can specify the exact version and base download URL as parameters to the
 ``use_setuptools()`` function.  See the function's docstring for details.)
 
 
+What Your Users Should Know
+---------------------------
+
+In general, a setuptools-based project looks just like any distutils-based
+project -- as long as your users have an internet connection and are installing
+to ``site-packages``, that is.  But for some users, these conditions don't
+apply, and they may become frustrated if this is their first encounter with
+a setuptools-based project.  To keep these users happy, you should review the
+following topics in your project's installation instructions, if they are
+relevant to your project and your target audience isn't already familiar with
+setuptools and ``easy_install``.
+
+Network Access
+    If your project is using ``ez_setup``, you should inform users of the need
+    to either have network access, or to preinstall the correct version of
+    setuptools using the `EasyInstall installation instructions`_.  Those
+    instructions also have tips for dealing with firewalls as well as how to
+    manually download and install setuptools.
+
+Custom Installation Locations
+    You should inform your users that if they are installing your project to
+    somewhere other than the main ``site-packages`` directory, they should
+    first install setuptools using the instructions for `Custom Installation
+    Locations`_, before installing your project.
+
+Your Project's Dependencies
+    If your project depends on other projects that may need to be downloaded
+    from PyPI or elsewhere, you should list them in your installation
+    instructions, or tell users how to find out what they are.  While most
+    users will not need this information, any users who don't have unrestricted
+    internet access may have to find, download, and install the other projects
+    manually.  (Note, however, that they must still install those projects
+    using ``easy_install``, or your project will not know they are installed,
+    and your setup script will try to download them again.)
+
+    If you want to be especially friendly to users with limited network access,
+    you may wish to build eggs for your project and its dependencies, making
+    them all available for download from your site, or at least create a page
+    with links to all of the needed eggs.  In this way, users with limited
+    network access can manually download all the eggs to a single directory,
+    then use the ``-f`` option of ``easy_install`` to specify the directory
+    to find eggs in.  Users who have full network access can just use ``-f``
+    with the URL of your download page, and ``easy_install`` will find all the
+    needed eggs using your links directly.  This is also useful when your
+    target audience isn't able to compile packages (e.g. most Windows users)
+    and your package or some of its dependencies include C code.
+
+Subversion or CVS Users and Co-Developers
+    Users and co-developers who are tracking your in-development code using
+    CVS, Subversion, or some other revision control system should probably read
+    this manual's sections regarding such development.  Alternately, you may
+    wish to create a quick-reference guide containing the tips from this manual
+    that apply to your particular situation.  For example, if you recommend
+    that people use ``setup.py develop`` when tracking your in-development
+    code, you should let them know that this needs to be run after every update
+    or commit.
+
+    Similarly, if you remove modules or data files from your project, you
+    should remind them to run ``setup.py clean --all`` and delete any obsolete
+    ``.pyc`` or ``.pyo``.  (This tip applies to the distutils in general, not
+    just setuptools, but not everybody knows about them; be kind to your users
+    by spelling out your project's best practices rather than leaving them
+    guessing.)
+
+Creating System Packages
+    Some users want to manage all Python packages using a single package
+    manager, and sometimes that package manager isn't ``easy_install``!
+    Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
+    ``bdist_dumb`` formats for system packaging.  If a user has a locally-
+    installed "bdist" packaging tool that internally uses the distutils
+    ``install`` command, it should be able to work with ``setuptools``.  If
+    it doesn't, please report the problem via the `mailing list`_ so that
+    either the "bdist" tool in question or setuptools can be modified to
+    resolve the issue.
+
+    Packaging tools that build binary distributions by running ``setup.py
+    install`` on the command line or as a subprocess can be made to work with
+    setuptools by using the ``--single-version-externally-managed`` option,
+    combined with the standard ``--root`` or ``--record`` options.
+    See the `install command`_ documentation below for more details.
+
+
 Managing Multiple Projects
 --------------------------
 
@@ -1773,6 +1854,8 @@ Other ``egg_info`` Options
     no ``package_dir`` set, this option defaults to the current directory.
 
 
+.. _install command:
+
 ``install`` - Run ``easy_install`` or old-style installation
 ============================================================