[4.2.x] Fixed #15578 -- Stated the processing order of fixtures in the fixtures docs.

Also, added details about loading multiple fixtures and unified line wrapping
at 79 cols.

Co-Authored-By: Aniketh Babu <anikethbabu@gmail.com>
Co-Authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>
Co-Authored-By: Natalia Bidart <124304+nessita@users.noreply.github.com>

Backport of 334dc073b1d9c89692aa5b11d362fb1cceae7a4a from main

1 files changed, 69 insertions, 34 deletions

diff --git a/docs/topics/db/fixtures.txt b/docs/topics/db/fixtures.txt
index 4db6de89eb..ab6ade9ca9 100644
--- a/docs/topics/db/fixtures.txt
+++ b/docs/topics/db/fixtures.txt
@@ -19,62 +19,104 @@ How to produce a fixture?
 =========================
 
 Fixtures can be generated by :djadmin:`manage.py dumpdata <dumpdata>`. It's
-also possible to generate custom fixtures by directly using
-:doc:`serialization documentation </topics/serialization>` tools or even by
-handwriting them.
+also possible to generate custom fixtures by directly using :doc:`serialization
+tools </topics/serialization>` or even by handwriting them.
 
-What to use a fixture for?
-==========================
+How to use a fixture?
+=====================
 
 Fixtures can be used to pre-populate database with data for
-:ref:`tests <topics-testing-fixtures>` or to provide some :ref:`initial data
-<initial-data-via-fixtures>`.
+:ref:`tests <topics-testing-fixtures>`:
+
+.. code-block:: python
+
+    class MyTestCase(TestCase):
+        fixtures = ["fixture-label"]
+
+or to provide some :ref:`initial data <initial-data-via-fixtures>` using the
+:djadmin:`loaddata` command:
+
+.. code-block:: shell
+
+    django-admin loaddata <fixture label>
+
 
 Where Django looks for fixtures?
 ================================
 
-Django will search in three locations for fixtures:
+Django will search in these locations for fixtures:
 
 1. In the ``fixtures`` directory of every installed application
-2. In any directory named in the :setting:`FIXTURE_DIRS` setting
+2. In any directory listed in the :setting:`FIXTURE_DIRS` setting
 3. In the literal path named by the fixture
 
 Django will load any and all fixtures it finds in these locations that match
-the provided fixture names.
-
-If the named fixture has a file extension, only fixtures of that type
-will be loaded. For example:
+the provided fixture names. If the named fixture has a file extension, only
+fixtures of that type will be loaded. For example:
 
 .. code-block:: shell
 
     django-admin loaddata mydata.json
 
-would only load JSON fixtures called ``mydata``. The fixture extension
-must correspond to the registered name of a
+would only load JSON fixtures called ``mydata``. The fixture extension must
+correspond to the registered name of a
 :ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``).
 
-If you omit the extensions, Django will search all available fixture types
-for a matching fixture. For example:
+If you omit the extensions, Django will search all available fixture types for
+a matching fixture. For example:
 
 .. code-block:: shell
 
     django-admin loaddata mydata
 
 would look for any fixture of any fixture type called ``mydata``. If a fixture
-directory contained ``mydata.json``, that fixture would be loaded
-as a JSON fixture.
+directory contained ``mydata.json``, that fixture would be loaded as a JSON
+fixture.
 
-The fixtures that are named can include directory components. These
-directories will be included in the search path. For example:
+The fixtures that are named can include directory components. These directories
+will be included in the search path. For example:
 
 .. code-block:: shell
 
     django-admin loaddata foo/bar/mydata.json
 
 would search ``<app_label>/fixtures/foo/bar/mydata.json`` for each installed
-application,  ``<dirname>/foo/bar/mydata.json`` for each directory in
+application, ``<dirname>/foo/bar/mydata.json`` for each directory in
 :setting:`FIXTURE_DIRS`, and the literal path ``foo/bar/mydata.json``.
 
+Fixtures loading order
+----------------------
+
+Multiple fixtures can be specified in the same invocation. For example:
+
+.. code-block:: shell
+
+    manage.py loaddata mammals birds insects
+
+or in a test case class:
+
+.. code-block:: python
+
+    class AnimalTestCase(TestCase):
+        fixtures = ["mammals", "birds", "insects"]
+
+The order in which fixtures are loaded follows the order in which they are
+listed, whether it's when using the management command or when listing them in
+the test case class as shown above.
+
+In these examples, all the fixtures named ``mammals`` from all applications (in
+the order in which applications are defined in :setting:`INSTALLED_APPS`) will
+be loaded first. Subsequently, all the ``birds`` fixtures will be loaded,
+followed by all the ``insects`` fixtures.
+
+Be aware that if the database backend supports row-level constraints, these
+constraints will be checked at the end of the transaction. Any relationships
+across fixtures may result in a load error if the database configuration does
+not support deferred constraint checking (refer to the `MySQL`_ docs for an
+example).
+
+.. _MySQL: https://dev.mysql.com/doc/refman/en/constraint-foreign-key.html
+
 How fixtures are saved to the database?
 =======================================
 
@@ -124,13 +166,7 @@ You could also write a decorator to encapsulate this logic::
         ...
 
 Just be aware that this logic will disable the signals whenever fixtures are
-deserialized, not just during ``loaddata``.
-
-Note that the order in which fixture files are processed is undefined. However,
-all fixture data is installed as a single transaction, so data in
-one fixture can reference data in another fixture. If the database backend
-supports row-level constraints, these constraints will be checked at the
-end of the transaction.
+deserialized, not just during :djadmin:`loaddata`.
 
 Compressed fixtures
 ===================
@@ -146,11 +182,10 @@ would look for any of ``mydata.json``, ``mydata.json.zip``, ``mydata.json.gz``,
 ``mydata.json.bz2``, ``mydata.json.lzma``, or ``mydata.json.xz``. The first
 file contained within a compressed archive is used.
 
-Note that if two fixtures with the same name but different
-fixture type are discovered (for example, if ``mydata.json`` and
-``mydata.xml.gz`` were found in the same fixture directory), fixture
-installation will be aborted, and any data installed in the call to
-``loaddata`` will be removed from the database.
+Note that if two fixtures with the same name but different fixture type are
+discovered (for example, if ``mydata.json`` and ``mydata.xml.gz`` were found in
+the same fixture directory), fixture installation will be aborted, and any data
+installed in the call to :djadmin:`loaddata` will be removed from the database.
 
 .. admonition:: MySQL with MyISAM and fixtures