Document how to lock most dependencies.

README.rst

@@ -546,6 +546,64 @@ on each targeted Python environment to avoid issues.
 
 .. _PEP 508 environment markers: https://www.python.org/dev/peps/pep-0508/#environment-markers
 
+Maximizing reproducibility
+==========================
+
+``pip-tools`` is a great tool to improve the reproducibility of builds.
+But there are a few things to keep in mind.
+
+* ``pip-compile`` will produce different results in different environments as described in the previous section.
+* ``pip`` must be used with the ``PIP_CONSTRAINT`` environment variable to lock dependencies in build environments as documented in `#8439`_.
+* Dependencies come from many sources.
+
+.. _#8439: https://github.com/pypa/pip/issues/8439
+
+Continuing the ``pyproject.toml`` example from earlier creating a single lock file could be done like:
+
+.. code-block:: console
+
+    $pip-compile --all-extras --build-system-requires --output-file=constraints.txt --strip-extras pyproject.toml
+    #
+    # This file is autogenerated by pip-compile with Python 3.9
+    # by the following command:
+    #
+    #    pip-compile --all-extras --build-system-requires --output-file=constraints.txt --strip-extras pyproject.toml
+    #
+    asgiref==3.5.2
+        # via django
+    attrs==22.1.0
+        # via pytest
+    django==4.1
+        # via my-cool-django-app (pyproject.toml)
+    editables==0.3
+        # via hatchling
+    hatchling==1.11.1
+        # via my-cool-django-app (pyproject.toml)
+    iniconfig==1.1.1
+        # via pytest
+    packaging==21.3
+        # via
+        #   hatchling
+        #   pytest
+    pathspec==0.10.2
+        # via hatchling
+    pluggy==1.0.0
+        # via
+        #   hatchling
+        #   pytest
+    py==1.11.0
+        # via pytest
+    pyparsing==3.0.9
+        # via packaging
+    pytest==7.1.2
+        # via my-cool-django-app (pyproject.toml)
+    sqlparse==0.4.2
+        # via django
+    tomli==2.0.1
+        # via
+        #   hatchling
+        #   pytest
+
 Other useful tools
 ==================
 

examples/readme/constraints.txt

@@ -0,0 +1,40 @@
+#
+# This file is autogenerated by pip-compile with Python 3.9
+# by the following command:
+#
+#    pip-compile --all-extras --build-system-requires --output-file=constraints.txt --strip-extras pyproject.toml
+#
+asgiref==3.5.2
+    # via django
+attrs==22.1.0
+    # via pytest
+django==4.1
+    # via my-cool-django-app (pyproject.toml)
+editables==0.3
+    # via hatchling
+hatchling==1.11.1
+    # via my-cool-django-app (pyproject.toml)
+iniconfig==1.1.1
+    # via pytest
+packaging==21.3
+    # via
+    #   hatchling
+    #   pytest
+pathspec==0.10.2
+    # via hatchling
+pluggy==1.0.0
+    # via
+    #   hatchling
+    #   pytest
+py==1.11.0
+    # via pytest
+pyparsing==3.0.9
+    # via packaging
+pytest==7.1.2
+    # via my-cool-django-app (pyproject.toml)
+sqlparse==0.4.2
+    # via django
+tomli==2.0.1
+    # via
+    #   hatchling
+    #   pytest

examples/readme/pyproject.toml

@@ -0,0 +1,11 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-cool-django-app"
+version = "42"
+dependencies = ["django"]
+
+[project.optional-dependencies]
+dev = ["pytest"]