[1.2.X] Fixed #13662 -- Added an entry in the README to direct people to the instructions for running the test suite, and cleaned up that section of the docs. Thanks to mir for the report, and to cogat and gg for the draft text.

Backport of r15342 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15345 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 82 insertions, 58 deletions

diff --git a/README b/README
index e748d9b7d0..c1cd37e0a0 100644
--- a/README
+++ b/README
@@ -35,3 +35,9 @@ To contribute to Django:
 
     * Check out http://www.djangoproject.com/community/ for information
       about getting involved.
+
+To run Django's test suite:
+
+    * Follow the instructions in the "Unit tests" section of
+      docs/internals/contributing.txt, published online at
+      http://docs.djangoproject.com/en/dev/internals/contributing/#running-the-unit-tests
diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt
index fd0e48b154..4ce6393181 100644
--- a/docs/internals/contributing.txt
+++ b/docs/internals/contributing.txt
@@ -827,29 +827,29 @@ discovered, please follow these guidelines:
       have a reversion policy doesn't relax your responsibility to aim for
       the highest quality possible. Really: double-check your work before
       you commit it in the first place!
-      
+
     * If possible, have the original author revert his/her own commit.
-      
+
     * Don't revert another author's changes without permission from the
       original author.
-      
+
     * If the original author can't be reached (within a reasonable amount
       of time -- a day or so) and the problem is severe -- crashing bug,
       major test failures, etc -- then ask for objections on django-dev
       then revert if there are none.
-      
+
     * If the problem is small (a feature commit after feature freeze,
       say), wait it out.
-      
+
     * If there's a disagreement between the committer and the
       reverter-to-be then try to work it out on the `django-developers`_
       mailing list. If an agreement can't be reached then it should
       be put to a vote.
-      
+
     * If the commit introduced a confirmed, disclosed security
       vulnerability then the commit may be reverted immediately without
       permission from anyone.
-    
+
     * The release branch maintainer may back out commits to the release
       branch without permission if the commit breaks the release branch.
 
@@ -878,14 +878,41 @@ for an explanation of how to write new tests.
 Running the unit tests
 ----------------------
 
-To run the tests, ``cd`` to the ``tests/`` directory and type:
+Quickstart
+~~~~~~~~~~
+
+Running the tests requires a Django settings module that defines the
+databases to use. To make it easy to get started. Django provides a
+sample settings module that uses the SQLite database. To run the tests
+with this sample ``settings`` module, ``cd`` into the Django
+``tests/`` directory and run:
+
+.. code-block:: bash
+
+    ./runtests.py --settings=test_sqlite
+
+If you get an ``ImportError: No module named django.contrib`` error,
+you need to add your install of Django to your ``PYTHONPATH``. For
+more details on how to do this, read `Pointing Python at the new
+Django version`_ below.
+
+Using another ``settings`` module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The included settings module allows you to run the test suite using
+SQLite. If you want to test behavior using a different database (and
+if you're proposing patches for Django, it's a good idea to test
+across databases), you may need to define your own settings file.
+
+To run the tests with different settings, ``cd`` to the ``tests/`` directory
+and type:
 
 .. code-block:: bash
 
     ./runtests.py --settings=path.to.django.settings
 
-Yes, the unit tests need a settings module, but only for database connection
-info. Your :setting:`DATABASES` setting needs to define two databases:
+The :setting:`DATABASES` setting in this test settings module needs to define
+two databases:
 
     * A ``default`` database. This database should use the backend that
       you want to use for primary testing
@@ -896,38 +923,8 @@ info. Your :setting:`DATABASES` setting needs to define two databases:
       want. It doesn't need to use the same backend as the ``default``
       database (although it can use the same backend if you want to).
 
-If you're using the SQLite database backend, you need to define
-:setting:`ENGINE` for both databases, plus a
-:setting:`TEST_NAME` for the ``other`` database. The
-following is a minimal settings file that can be used to test SQLite::
-
-    DATABASES = {
-        'default': {
-            'ENGINE': 'django.db.backends.sqlite3'
-        },
-        'other': {
-            'ENGINE': 'django.db.backends.sqlite3',
-            'TEST_NAME': 'other_db'
-        }
-    }
-
-As a convenience, this settings file is included in your Django
-distribution. It is called ``test_sqlite``, and is included in
-the ``tests`` directory. This allows you to get started running
-the tests against the sqlite database without doing anything on
-your filesystem. However it should be noted that running against
-other database backends is recommended for certain types of test
-cases.
-
-To run the tests with this included settings file, ``cd``
-to the ``tests/`` directory and type:
-
-.. code-block:: bash
-
-    ./runtests.py --settings=test_sqlite
-
-If you're using another backend, you will need to provide other details for
-each database:
+If you're using a backend that isn't SQLite, you will need to provide other
+details for each database:
 
     * The :setting:`USER` option for each of your databases needs to
       specify an existing user account for the database.
@@ -947,6 +944,40 @@ character set. If your database server doesn't use UTF-8 as a default charset,
 you will need to include a value for ``TEST_CHARSET`` in the settings
 dictionary for the applicable database.
 
+Running only some of the tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django's entire test suite takes a few minutes to run. To run a subset of the
+unit tests, append the names of the test modules to the ``runtests.py``
+command line.
+
+As an example, if you'd like to only run tests for generic relations and
+internationalization, type:
+
+.. code-block:: bash
+
+    ./runtests.py --settings=path.to.settings generic_relations i18n
+
+See the list of directories in ``tests/modeltests`` and
+``tests/regressiontests`` for module names.
+
+If you just want to run a particular class of tests, you can specify a list of
+paths to individual test classes. For example, to run the ``TranslationTests``
+of the ``i18n`` module, type:
+
+.. code-block:: bash
+
+    ./runtests.py --settings=path.to.settings i18n.TranslationTests
+
+You can specify an individual test like this:
+
+.. code-block:: bash
+
+    ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
+
+Running all the tests
+~~~~~~~~~~~~~~~~~~~~~
+
 If you want to run the full suite of tests, you'll need to install a number of
 dependencies:
 
@@ -975,19 +1006,6 @@ associated tests will be skipped.
 .. _cmemcached: http://gijsbert.org/cmemcache/index.html
 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
 
-To run a subset of the unit tests, append the names of the test modules to the
-``runtests.py`` command line. See the list of directories in
-``tests/modeltests`` and ``tests/regressiontests`` for module names.
-
-As an example, if Django is not in your ``PYTHONPATH``, you placed
-``settings.py`` in the ``tests/`` directory, and you'd like to only run tests
-for generic relations and internationalization, type:
-
-.. code-block:: bash
-
-    PYTHONPATH=`pwd`/..
-    ./runtests.py --settings=settings generic_relations i18n
-
 Contrib apps
 ------------
 
@@ -1234,9 +1252,9 @@ voting mechanism above. A proposition will be considered carried by the core tea
 if:
 
     * There are three "+1" votes from members of the core team.
-    
+
     * There is no "-1" vote from any member of the core team.
-    
+
     * The BDFLs haven't stepped in and executed their positive or negative
       veto.
 
@@ -1263,7 +1281,7 @@ Core committers
     codebase, a solid track record of being polite and helpful on the
     mailing lists, and a proven desire to dedicate serious time to Django's
     development. The bar is high for full commit access.
-    
+
 Partial committers
     These are people who are "domain experts." They have direct check-in access
     to the subsystems that fall under their jurisdiction, and they're given a