From 285e765891149704cbd5ddb784887ad187416ef7 Mon Sep 17 00:00:00 2001
From: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue, 24 Dec 2013 19:00:29 +0100
Subject: [PATCH] Added release notes for app loading changes.

---
 docs/ref/applications.txt |  4 ++--
 docs/ref/settings.txt     |  9 +++++++++
 docs/releases/1.7.txt     | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index 0f5090cf1a..5d13d0d4d8 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -124,8 +124,8 @@ Application registry
 .. method:: django.apps.apps.get_app_config(app_label, only_with_models_module=False)
 
     Returns an :class:`~django.apps.AppConfig` for the application with the
-    given ``app_label``. Raises :exc:`LookupError` if no such application
-    exists.
+    given ``app_label``. Raises :exc:`~exceptions.LookupError` if no such
+    application exists.
 
     If only applications containing a models module are of interest, this method
     can be called with ``only_with_models_module=True``.
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index fbd06976cc..d82f68a2a4 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1290,6 +1290,15 @@ Django installation. Each string should be a full Python path to an
 application configuration class or to a Python package containing a
 application. :ref:` Learn more about applications </ref/applications>`.
 
+.. versionchanged:: 1.7
+
+    :setting:`INSTALLED_APPS` now supports application configurations.
+
+.. admonition:: Use the application registry for introspection
+
+    Your code should never access :setting:`INSTALLED_APPS` directly. Use the
+    app registry, :attr:`~django.apps.apps`, instead.
+
 .. admonition:: Application labels must be unique
 
     Application labels (that is, the final part of the dotted path to
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 106de20ec1..ab2aa3442b 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -58,6 +58,27 @@ but a few of the key features are:
   will still work, but that method name is deprecated and you should change
   it as soon as possible (nothing more than renaming is required).
 
+App-loading refactor
+~~~~~~~~~~~~~~~~~~~~
+
+Historically, Django applications were tightly linked to models. A singleton
+known as the "app cache" dealt with both installed applications and models.
+The models module was used as an identifier for applications in many APIs.
+
+As the concept of :doc:`Django applications </ref/applications>` matured, this
+code showed some shortcomings. It was refactored into an "app registry" where
+models modules no longer have a central role models and where it's possible to
+attach configuration data to applications.
+
+Not only does this prepare the ground for further improvements, but it also
+brings some concrete improvements:
+
+* It is possible to omit ``models.py`` entirely if an application doesn't
+  have any models.
+
+* The name of applications can be customized in the admin with the
+  :attr:`~django.apps.AppConfig.verbose_name` of application configurations.
+
 New method on Field subclasses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -570,6 +591,22 @@ For apps with migrations, ``allow_migrate`` will now get passed
 without custom attributes, methods or managers. Make sure your ``allow_migrate``
 methods are only referring to fields or other items in ``model._meta``.
 
+App-loading changes
+~~~~~~~~~~~~~~~~~~~
+
+Since :setting:`INSTALLED_APPS` now supports application configuration classes
+in addition to application modules, you should review code that accesses this
+setting directly and use the app registry (:attr:`django.apps.apps`) instead.
+
+The "app registry" that manages the list of installed applications doesn't
+have the same features as the old "app cache". However, even though the "app
+cache" was a private API, most of its methods were temporarily preserved and
+will go through a deprecation path.
+
+While the new implementation is believed to be more robust, regressions cannot
+be ruled out, especially during the import sequence. Circular imports that
+didn't happen with previous versions of Django might appear.
+
 Behavior of ``LocMemCache`` regarding pickle errors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~