Fixed #35084 -- Recommended 'django_' prefix for reusable app modules.

1 files changed, 51 insertions, 28 deletions

diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
index 19d9063edd..f40daf4dfb 100644
--- a/docs/intro/reusable-apps.txt
+++ b/docs/intro/reusable-apps.txt
@@ -121,16 +121,17 @@ Python *packaging* refers to preparing your app in a specific format that can
 be easily installed and used. Django itself is packaged very much like
 this. For a small app like polls, this process isn't too difficult.
 
-#. First, create a parent directory for ``polls``, outside of your Django
+#. First, create a parent directory for the package, outside of your Django
    project. Call this directory ``django-polls``.
 
    .. admonition::  Choosing a name for your app
 
-       When choosing a name for your package, check resources like PyPI to avoid
-       naming conflicts with existing packages. It's often useful to prepend
-       ``django-`` to your module name when creating a package to distribute.
-       This helps others looking for Django apps identify your app as Django
-       specific.
+       When choosing a name for your package, check PyPI to avoid naming
+       conflicts with existing packages. We recommend using a ``django-``
+       prefix for package names, to identify your package as specific to
+       Django, and a corresponding ``django_`` prefix for your module name. For
+       example, the ``django-ratelimit`` package contains the
+       ``django_ratelimit`` module.
 
        Application labels (that is, the final part of the dotted path to
        application packages) *must* be unique in :setting:`INSTALLED_APPS`.
@@ -138,19 +139,35 @@ this. For a small app like polls, this process isn't too difficult.
        </ref/contrib/index>`, for example ``auth``, ``admin``, or
        ``messages``.
 
-#. Move the ``polls`` directory into the ``django-polls`` directory.
+#. Move the ``polls`` directory into ``django-polls`` directory, and rename it
+   to ``django_polls``.
+
+#. Edit ``django_polls/apps.py`` so that :attr:`~.AppConfig.name` refers to the
+   new module name and add :attr:`~.AppConfig.label` to give a short name for
+   the app:
+
+   .. code-block:: python
+       :caption: ``django-polls/django_polls/apps.py``
+
+       from django.apps import AppConfig
+
+
+       class PollsConfig(AppConfig):
+           default_auto_field = "django.db.models.BigAutoField"
+           name = "django_polls"
+           label = "polls"
 
 #. Create a file ``django-polls/README.rst`` with the following contents:
 
    .. code-block:: rst
        :caption: ``django-polls/README.rst``
 
-       =====
-       Polls
-       =====
+       ============
+       django-polls
+       ============
 
-       Polls is a Django app to conduct web-based polls. For each question,
-       visitors can choose between a fixed number of answers.
+       django-polls is a Django app to conduct web-based polls. For each
+       question, visitors can choose between a fixed number of answers.
 
        Detailed documentation is in the "docs" directory.
 
@@ -161,19 +178,18 @@ this. For a small app like polls, this process isn't too difficult.
 
            INSTALLED_APPS = [
                ...,
-               "polls",
+               "django_polls",
            ]
 
        2. Include the polls URLconf in your project urls.py like this::
 
-           path("polls/", include("polls.urls")),
+           path("polls/", include("django_polls.urls")),
 
-       3. Run ``python manage.py migrate`` to create the polls models.
+       3. Run ``python manage.py migrate`` to create the models.
 
-       4. Start the development server and visit http://127.0.0.1:8000/admin/
-          to create a poll (you'll need the Admin app enabled).
+       4. Start the development server and visit the admin to create a poll.
 
-       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
+       5. Visit the ``/polls/`` URL to participate in the poll.
 
 #. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the
    scope of this tutorial, but suffice it to say that code released publicly
@@ -251,8 +267,8 @@ this. For a small app like polls, this process isn't too difficult.
 
        include LICENSE
        include README.rst
-       recursive-include polls/static *
-       recursive-include polls/templates *
+       recursive-include django_polls/static *
+       recursive-include django_polls/templates *
 
 #. It's optional, but recommended, to include detailed documentation with your
    app. Create an empty directory ``django-polls/docs`` for future
@@ -266,8 +282,8 @@ this. For a small app like polls, this process isn't too difficult.
    you add some files to it. Many Django apps also provide their documentation
    online through sites like `readthedocs.org <https://readthedocs.org>`_.
 
-#. Try building your package with ``python setup.py sdist`` (run from inside
-   ``django-polls``). This creates a directory called ``dist`` and builds your
+#. Try building your package by running ``python setup.py sdist`` inside
+   ``django-polls``. This creates a directory called ``dist`` and builds your
    new package, ``django-polls-0.1.tar.gz``.
 
 For more information on packaging, see Python's `Tutorial on Packaging and
@@ -299,14 +315,21 @@ working. We'll now fix this by installing our new ``django-polls`` package.
 
       python -m pip install --user django-polls/dist/django-polls-0.1.tar.gz
 
-#. With luck, your Django project should now work correctly again. Run the
-   server again to confirm this.
+#. Update ``mysite/settings.py`` to point to the new module name::
 
-#. To uninstall the package, use pip:
+    INSTALLED_APPS = [
+        "django_polls.apps.PollsConfig",
+        ...,
+    ]
 
-   .. code-block:: shell
+#. Update ``mysite/urls.py`` to point to the new module name::
+
+    urlpatterns = [
+        path("polls/", include("django_polls.urls")),
+        ...,
+    ]
 
-      python -m pip uninstall django-polls
+#. Run the development server to confirm the project continues to work.
 
 Publishing your app
 ===================
@@ -326,7 +349,7 @@ the world! If this wasn't just an example, you could now:
 Installing Python packages with a virtual environment
 =====================================================
 
-Earlier, we installed the polls app as a user library. This has some
+Earlier, we installed ``django-polls`` as a user library. This has some
 disadvantages:
 
 * Modifying the user libraries can affect other Python software on your system.