Update requirements files comments

Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Co-Authored-By: Joshua Lock <jlock@vmware.com>

requirements-dev.txt

@@ -1,8 +1,5 @@
-# Install tox for local testing, but also everything that tox would install
-# in a test environment, so that we can run the test suite or individual tests
-# directly in the development environment as well.
+# Install tuf in editable mode and requirements for local testing with tox,
+# and also for running test suite or individual tests manually
 tox
 -r requirements-tox.txt
-
-# Install tuf in editable mode
 -e .

requirements-pinned.txt

@@ -1,34 +1,4 @@
-# These pinned requirements are the combined results of `pip-compile` over
-# "requirements.in" in each supported Python version.
-#
-# - Below script may be used (copy-paste to bash removing leading '#') to
-#   re-generate this file, e.g. if `requirements.in` is updated.
-# - Version updates should be handled by a GitHub-integrated dependency monitor
-#   (e.g. Dependabot) that regularly scans PyPI for updates, patches this file,
-#   and submits a PR, which triggers CI/CD builds and should catch breaking
-#   updates.
-#
-# # Gather pip-compile results for each supported Python version
-# for v in 2.7 3.5 3.6 3.7 3.8; do
-#   mkvirtualenv tuf-env-${v} -p python${v};
-#   pip install pip-tools;
-#   pip-compile requirements.in -n 2>&1 | grep -v "^#"  >> requirements.combined;
-#   # Keep one venv as we need it below to add hashes
-#   if [ $v != 3.8 ]; then
-#     deactivate;
-#     rmvirtualenv tuf-env-${v};
-#   fi
-# done;
-# # Create requirements-pinned.txt retaining doc header
-# cat requirements-pinned.txt | grep "^#"  > requirements.tmp
-# mv requirements.tmp requirements-pinned.txt
-# cat requirements.combined | grep -v "^Dry-run," | sort -u >> requirements-pinned.txt
-# rm requirements.combined
-# # Create requirements.txt with hashes
-# pip-compile --generate-hashes -o requirements.txt requirements-pinned.txt
-# deactivate
-# rmvirtualenv tuf-env-3.8
-#
+# Auto-generated (see requirements.in)
 certifi==2019.11.28       # via requests
 cffi==1.13.2              # via cryptography, pynacl
 chardet==3.0.4            # via requests

requirements-test.txt

@@ -1,2 +1,2 @@
-# Runtime requirements for test suite
+# Install test requirements (see 'tests_require' field in setup.py)
 mock; python_version < "3.3"

requirements-tox.txt

@@ -1,10 +1,12 @@
-# pinned tuf runtime dependencies
+# Install requirements needed in each tox environment
+
+# pinned tuf runtime dependencies (should auto-update and -trigger ci/cd)
 -r requirements-pinned.txt
 
-# tuf test suite runtime dependencies
+# test runtime dependencies
 -r requirements-test.txt
 
-# test tools for linting and test coverage measurement
+# additional test tools for linting and coverage measurement
 coverage
 pylint
 bandit

requirements.in

@@ -1,5 +1,42 @@
-# requirements.in for pip-compile.
-
+# Template for tuf runtime requirements files including optional dependencies
+#
+# Copy-paste script below (without leading '#') to bash when requirements are
+# added or removed to generate:
+#
+# - 'requirements.txt': lists pinned dependencies with hashes, used for
+#   client-side integrity checks
+#
+# - 'requirements-pinned.txt': lists pinned dependencies without hashes, used
+#   for ci/cd builds, where 'requirements.txt' can't be used together with
+#   other (non-runtime) requirements that don't list hashes (see pypa/pip#4995)
+#
+# Both files are automatically updated on GitHub with Dependabot.
+#
+# -----------------------------------------------------------------------------
+# # Gather pip-compile results for each supported Python version
+# for v in 2.7 3.5 3.6 3.7 3.8; do
+#   mkvirtualenv tuf-env-${v} -p python${v};
+#   pip install pip-tools;
+#   pip-compile requirements.in -n 2>&1 | grep -v "^#"  >> requirements.combined;
+#   # Keep one venv as we need it below to add hashes
+#   if [ $v != 3.8 ]; then
+#     deactivate;
+#     rmvirtualenv tuf-env-${v};
+#   fi
+# done;
+#
+# # Create requirements-pinned.txt
+# echo "# Auto-generated (see requirements.in)" > requirements-pinned.txt
+# cat requirements.combined | grep -v "^Dry-run," | sort -u >> requirements-pinned.txt
+# rm requirements.combined
+#
+# # Create requirements.txt with hashes
+# pip-compile --generate-hashes -o requirements.txt requirements-pinned.txt
+#
+# # Remove remaining venv
+# deactivate
+# rmvirtualenv tuf-env-3.8
+# -----------------------------------------------------------------------------
 securesystemslib
 cryptography
 colorama