[4.2.x] Fixed #34146 -- Added 3rd-party lib tutorial step.

Added a tutorial step that highlights Django Debug Toolbar, on of the
most common third party packages. It also added a mention of
djangopackages.com as a place to search for other libraries and a
link to Adam Johnson’s post on evaluating whether a package is
well-maintained.

Third-party packages are one of Django’s strengths. This should give
folks a sound route in.

Backport of 7715c9f and
1df7814 from main

docs/index.txt

@@ -22,7 +22,8 @@ Are you new to Django or to programming? This is the place to start!
   :doc:`Part 4: Forms and generic views <intro/tutorial04>` |
   :doc:`Part 5: Testing <intro/tutorial05>` |
   :doc:`Part 6: Static files <intro/tutorial06>` |
-  :doc:`Part 7: Customizing the admin site <intro/tutorial07>`
+  :doc:`Part 7: Customizing the admin site <intro/tutorial07>` |
+  :doc:`Part 8: Adding third-party packages <intro/tutorial08>`
 
 * **Advanced Tutorials:**
   :doc:`How to write reusable apps <intro/reusable-apps>` |

docs/intro/index.txt

@@ -17,6 +17,7 @@ place: read this material to quickly get up and running.
    tutorial05
    tutorial06
    tutorial07
+   tutorial08
    reusable-apps
    whatsnext
    contributing

docs/intro/reusable-apps.txt

@@ -2,7 +2,7 @@
 Advanced tutorial: How to write reusable apps
 =============================================
 
-This advanced tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>`
+This advanced tutorial begins where :doc:`Tutorial 8 </intro/tutorial08>`
 left off. We'll be turning our web-poll into a standalone Python package
 you can reuse in new projects and share with other people.
 

docs/intro/tutorial07.txt

@@ -418,12 +418,5 @@ uses a template variable called ``app_list``. That variable contains every
 installed Django app. Instead of using that, you can hard-code links to
 object-specific admin pages in whatever way you think is best.
 
-What's next?
-============
-
-The beginner tutorial ends here. In the meantime, you might want to check out
-some pointers on :doc:`where to go from here </intro/whatsnext>`.
-
-If you are familiar with Python packaging and interested in learning how to
-turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
-write reusable apps</intro/reusable-apps>`.
+When you're comfortable with the admin, read :doc:`part 8 of this
+tutorial </intro/tutorial08>` to learn how to use third-party packages.

docs/intro/tutorial08.txt

@@ -0,0 +1,101 @@
+=====================================
+Writing your first Django app, part 8
+=====================================
+
+This tutorial begins where :doc:`Tutorial 7 </intro/tutorial07>` left off. We've
+built our web-poll application and will now look at third-party packages. One of
+Django's strengths is the rich ecosystem of third-party packages. They're
+community developed packages that can be used to quickly improve the feature set
+of an application.
+
+This tutorial will show how to add `Django Debug Toolbar
+<https://django-debug-toolbar.readthedocs.io>`_, a commonly used third-party
+package. The Django Debug Toolbar has ranked in the top three most used
+third-party packages in the Django Developers Survey in recent years.
+
+.. admonition:: Where to get help:
+
+    If you're having trouble going through this tutorial, please head over to
+    the :doc:`Getting Help</faq/help>` section of the FAQ.
+
+Installing Django Debug Toolbar
+===============================
+
+Django Debug Toolbar is a useful tool for debugging Django web applications.
+It's a third-party package maintained by the `Jazzband
+<https://jazzband.co>`_ organization. The toolbar helps you understand how your
+application functions and to identify problems. It does so by providing panels
+that provide debug information about the current request and response.
+
+To install a third-party application like the toolbar, you need to install
+the package by running the below command within an activated virtual
+environment. This is similar to our earlier step to :ref:`install Django
+<installing-official-release>`.
+
+.. console::
+
+    $ python -m pip install django-debug-toolbar
+
+Third-party packages that integrate with Django need some post-installation
+setup to integrate them with your project. Often you will need to add the
+package's Django app to your :setting:`INSTALLED_APPS` setting. Some packages
+need other changes, like additions to your URLconf (``urls.py``).
+
+Django Debug Toolbar requires several setup steps. Follow them in `its
+installation guide
+<https://django-debug-toolbar.readthedocs.io/en/latest/installation.html>`_.
+The steps are not duplicated in this tutorial, because as a third-party
+package, it may change separately to Django's schedule.
+
+Once installed, you should be able to see the DjDT "handle" on the right side
+of the browser window when you refresh the polls application. Click it to open
+the debug toolbar and use the tools in each panel. See the `panels
+documentation page
+<https://django-debug-toolbar.readthedocs.io/en/latest/panels.html>`__ for more
+information on what the panels show.
+
+Getting help from others
+========================
+
+At some point you will run into a problem, for example the
+toolbar may not render. When this happens and you're unable to
+resolve the issue yourself, there are options available to you.
+
+#. If the problem is with a specific package, check if there's a
+   troubleshooting of FAQ in the package's documentation. For example the
+   Django Debug Toolbar has a `Tips section
+   <https://django-debug-toolbar.readthedocs.io/en/latest/tips.html>`_ that
+   outlines troubleshooting options.
+#. Search for similar issues on the package's issue tracker. Django Debug
+   Toolbar’s is `on GitHub <https://github.com/jazzband/django-debug-toolbar/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc>`_.
+#. Consult the `Django Forum <https://forum.djangoproject.com/>`_.
+#. Join the `Django Discord server <https://discord.gg/xcRH6mN4fa>`_.
+#. Join the #Django IRC channel on `Libera.chat <https://libera.chat/>`_.
+
+Installing other third-party packages
+=====================================
+
+There are many more third-party packages, which you can find using the
+fantastic Django resource, `Django Packages <https://djangopackages.org/>`_.
+
+It can be difficult to know what third-party packages you should use. This
+depends on your needs and goals. Sometimes it's fine to use a package that's
+in its alpha state. Other times, you need to know it's production ready.
+`Adam Johnson has a blog post
+<https://adamj.eu/tech/2021/11/04/the-well-maintained-test/>`_ that outlines
+a set of characteristics a that qualifies a package as "well maintained".
+Django Packages shows data for some of these characteristics, such as when the
+package was last updated.
+
+As Adam points out in his post, when the answer to one of the questions is
+"no", that's an opportunity to contribute.
+
+What's next?
+============
+
+The beginner tutorial ends here. In the meantime, you might want to check out
+some pointers on :doc:`where to go from here </intro/whatsnext>`.
+
+If you are familiar with Python packaging and interested in learning how to
+turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
+write reusable apps</intro/reusable-apps>`.

docs/spelling_wordlist

@@ -235,6 +235,7 @@ iterable
 iterables
 iteratively
 ize
+Jazzband
 Jinja
 jQuery
 Jupyter