Browse Source

Added release notes for app loading changes.

Aymeric Augustin 11 years ago
parent
commit
285e765891
3 changed files with 48 additions and 2 deletions
  1. 2 2
      docs/ref/applications.txt
  2. 9 0
      docs/ref/settings.txt
  3. 37 0
      docs/releases/1.7.txt

+ 2 - 2
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``.

+ 9 - 0
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

+ 37 - 0
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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~