Fixed #21829 -- Added default AppConfigs.

Thanks Russell for the report, Marc for the initial patch, Carl for the
final review, and everyone who contributed to the design discussion.

6 files changed, 74 insertions, 45 deletions

diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt
index 1bf11e47ae..16b2596da9 100644
--- a/docs/intro/tutorial01.txt
+++ b/docs/intro/tutorial01.txt
@@ -435,7 +435,7 @@ look like this:
     :filename: mysite/settings.py
 
     INSTALLED_APPS = (
-        'django.contrib.admin.apps.AdminConfig',
+        'django.contrib.admin',
         'django.contrib.auth',
         'django.contrib.contenttypes',
         'django.contrib.sessions',
@@ -444,13 +444,6 @@ look like this:
         'polls',
     )
 
-.. admonition:: Doesn't match what you see?
-
-    If you're seeing ``'django.contrib.admin'`` instead of
-    ``'django.contrib.admin.apps.AdminConfig'``, you're probably using a
-    version of Django that doesn't match this tutorial version.  You'll want
-    to either switch to the older tutorial or the newer Django version.
-
 Now Django knows to include the ``polls`` app. Let's run another command:
 
 .. code-block:: bash
diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index e496f24487..33f885e416 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -49,9 +49,15 @@ Configuring applications
 To configure an application, subclass :class:`~django.apps.AppConfig` and put
 the dotted path to that subclass in :setting:`INSTALLED_APPS`.
 
-Django uses the default :class:`~django.apps.AppConfig` class when
-:setting:`INSTALLED_APPS` simply contains the dotted path to an application
-module.
+When :setting:`INSTALLED_APPS` simply contains the dotted path to an
+application module, Django checks for a ``default_app_config`` variable in
+that module.
+
+If it's defined, it's the dotted path to the :class:`~django.apps.AppConfig`
+subclass for that application.
+
+If there is no ``default_app_config``, Django uses the base
+:class:`~django.apps.AppConfig` class.
 
 For application authors
 -----------------------
@@ -67,8 +73,23 @@ would provide a proper name for the admin::
         name = 'rock_n_roll'
         verbose_name = "Rock ’n’ roll"
 
-You would then tell your users to add ``'rock_n_roll.apps.RockNRollConfig'``
-to their :setting:`INSTALLED_APPS`.
+You can make your application load this :class:`~django.apps.AppConfig`
+subclass by default as follows::
+
+    # rock_n_roll/__init__.py
+
+    default_app_config = 'rock_n_roll.apps.RockNRollConfig'
+
+That will cause ``RockNRollConfig`` to be used when :setting:`INSTALLED_APPS`
+just contains ``'rock_n_roll'``. This allows you to make use of
+:class:`~django.apps.AppConfig` features without requiring your users to
+update their :setting:`INSTALLED_APPS` setting.
+
+Of course, you can also tell your users to put
+``'rock_n_roll.apps.RockNRollConfig'`` in their :setting:`INSTALLED_APPS`
+setting. You can even provide several different
+:class:`~django.apps.AppConfig` subclasses with different behaviors and allow
+your users to choose one via their :setting:`INSTALLED_APPS` setting.
 
 The recommended convention is to put the configuration class in a submodule of
 the application called ``apps``. However, this isn't enforced by Django.
@@ -87,7 +108,7 @@ configuration::
 
     # anthology/apps.py
 
-    from rock_n_roll.app import RockNRollConfig
+    from rock_n_roll.apps import RockNRollConfig
 
     class GypsyJazzConfig(RockNRollConfig):
         verbose_name = "Gypsy jazz"
@@ -213,7 +234,7 @@ Application registry
 .. method:: apps.is_installed(app_name)
 
     Checks whether an application with the given name exists in the registry.
-    ``app_name`` is the full name of the app, e.g. 'django.contrib.admin'.
+    ``app_name`` is the full name of the app, e.g. ``'django.contrib.admin'``.
 
     Unlike :meth:`~django.apps.apps.get_app_config`, this method can be called
     safely at import time. If the registry is still being populated, it may
diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 7fc34c96de..281ea4674b 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -23,12 +23,7 @@ The admin is enabled in the default project template used by
 
 For reference, here are the requirements:
 
-1. Add ``'django.contrib.admin.apps.AdminConfig'`` to your
-   :setting:`INSTALLED_APPS` setting.
-
-   .. versionchanged:: 1.7
-
-       :setting:`INSTALLED_APPS` used to contain ``'django.contrib.admin'``.
+1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS` setting.
 
 2. The admin has four dependencies - :mod:`django.contrib.auth`,
    :mod:`django.contrib.contenttypes`,
@@ -136,16 +131,23 @@ The register decorator
 Discovery of admin files
 ------------------------
 
-The admin needs to be instructed to look for ``admin.py`` files in your project.
-The easiest solution is to put ``'django.contrib.admin.apps.AdminConfig'`` in
-your :setting:`INSTALLED_APPS` setting.
+When you put ``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS`
+setting, Django automatically looks for an ``admin`` module in each
+application and imports it.
 
 .. class:: apps.AdminConfig
 
     .. versionadded:: 1.7
 
-    This class calls :func:`~django.contrib.admin.autodiscover()` when Django
-    starts.
+    This is the default :class:`~django.apps.AppConfig` class for the admin.
+    It calls :func:`~django.contrib.admin.autodiscover()` when Django starts.
+
+.. class:: apps.SimpleAdminConfig
+
+    .. versionadded:: 1.7
+
+    This class works like :class:`~django.contrib.admin.apps.AdminConfig`,
+    except it doesn't call :func:`~django.contrib.admin.autodiscover()`.
 
 .. function:: autodiscover
 
@@ -155,13 +157,23 @@ your :setting:`INSTALLED_APPS` setting.
     .. versionchanged:: 1.7
 
         Previous versions of Django recommended calling this function directly
-        in the URLconf. :class:`~django.contrib.admin.apps.AdminConfig`
-        replaces that mechanism and is more robust.
+        in the URLconf. As of Django 1.7 this isn't needed anymore.
+        :class:`~django.contrib.admin.apps.AdminConfig` takes care of running
+        the auto-discovery automatically.
 
 If you are using a custom ``AdminSite``, it is common to import all of the
 ``ModelAdmin`` subclasses into your code and register them to the custom
-``AdminSite``. In that case, simply put ``'django.contrib.admin'`` in your
-:setting:`INSTALLED_APPS` setting, as you don't need autodiscovery.
+``AdminSite``. In that case, in order to disable auto-discovery, you should
+put ``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of
+``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS` setting.
+
+.. versionchanged:: 1.7
+
+    In previous versions, the admin needed to be instructed to look for
+    ``admin.py`` files with :func:`~django.contrib.admin.autodiscover()`.
+    As of Django 1.7, auto-discovery is enabled by default and must be
+    explicitly disabled when it's undesirable.
+
 
 ``ModelAdmin`` options
 ----------------------
@@ -2426,11 +2438,12 @@ In this example, we register the ``AdminSite`` instance
         (r'^myadmin/', include(admin_site.urls)),
     )
 
-Note that you don't need autodiscovery of ``admin`` modules when using your
+Note that you may not want autodiscovery of ``admin`` modules when using your
 own ``AdminSite`` instance since you will likely be importing all the per-app
-``admin`` modules in your ``myproject.admin`` module. This means you likely do
-not need ``'django.contrib.admin.app.AdminConfig'`` in your
-:setting:`INSTALLED_APPS` and can just use ``'django.contrib.admin'``.
+``admin`` modules in your ``myproject.admin`` module. This means you need to
+put ``'django.contrib.admin.app.SimpleAdminConfig'`` instead of
+``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS` setting.
+
 
 Multiple admin sites in the same URLconf
 ----------------------------------------
diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index f3eeb64e59..ff27c9b6ec 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -115,7 +115,7 @@ In addition, modify the :setting:`INSTALLED_APPS` setting to include
 and ``world`` (your newly created application)::
 
     INSTALLED_APPS = (
-        'django.contrib.admin.apps.AdminConfig',
+        'django.contrib.admin',
         'django.contrib.auth',
         'django.contrib.contenttypes',
         'django.contrib.sessions',
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index df115c6c15..684daa988c 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -89,17 +89,14 @@ Improvements thus far include:
 * The name of applications can be customized in the admin with the
   :attr:`~django.apps.AppConfig.verbose_name` of application configurations.
 
+* The admin automatically calls :func:`~django.contrib.admin.autodiscover()`
+  when Django starts. You can consequently remove this line from your
+  URLconf.
+
 * Django imports all application configurations and models as soon as it
   starts, through a deterministic and straightforward process. This should
   make it easier to diagnose import issues such as import loops.
 
-* The admin has an :class:`~django.contrib.admin.apps.AdminConfig` application
-  configuration class. When Django starts, this class takes care of calling
-  :func:`~django.contrib.admin.autodiscover()`. To use it, simply replace
-  ``'django.contrib.admin'`` in :setting:`INSTALLED_APPS` with
-  ``'django.contrib.admin.apps.AdminConfig'`` and remove
-  ``admin.autodiscover()`` from your URLconf.
-
 New method on Field subclasses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -698,6 +695,12 @@ regressions cannot be ruled out. You may encounter the following exceptions:
   results. The code will be executed when you first need its results. This
   concept is known as "lazy evaluation".
 
+* ``django.contrib.admin`` will now automatically perform autodiscovery of
+  ``admin`` modules in installed applications. To prevent it, change your
+  :setting:`INSTALLED_APPS` to contain
+  ``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of
+  ``'django.contrib.admin'``.
+
 Standalone scripts
 ^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index bfac4c922e..a721fb548c 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -67,9 +67,8 @@ Creating superusers
 -------------------
 
 :djadmin:`manage.py migrate <migrate>` prompts you to create a superuser the
-first time you run it with ``'django.contrib.auth'`` in your
-:setting:`INSTALLED_APPS`. If you need to create a superuser at a later date,
-you can use a command line utility::
+first time you run it with ``'django.contrib.auth'`` installed. If you need to
+create a superuser at a later date, you can use a command line utility::
 
     $ python manage.py createsuperuser --username=joe --email=joe@example.com