Clarified comments in requirements/constraints files

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

dev-requirements.txt

@@ -1,17 +1,12 @@
-# Pip requirements file for development.
-#
-# The order of packages is significant, because pip processes them in the order
-# of appearance.
-#
-# Make sure that the minimum versions required in this file are consistent with
-# the minimum versions specified in minimum-constraints.txt.
+# Pip requirements file for development dependencies.
 
 
-# Runtime dependencies:
+# Include install dependencies
 -r requirements.txt
 
 
-# Direct dependencies:
+# Direct dependencies for development and indirect dependencies for development
+# that are needed for some reason (must be consistent with minimum-constraints.txt)
 
 # Ansible validate-modules (no imports, invoked via validate-modules script)
 mock>=2.0.0
@@ -183,5 +178,3 @@ pip-check-reqs>=2.3.2; python_version >= '3.5' and python_version <= '3.7'
 # pip-check-reqs 2.5.0 has issue https://github.com/r1chardj0n3s/pip-check-reqs/issues/143
 pip-check-reqs>=2.4.3,!=2.5.0; python_version >= '3.8' and python_version <= '3.11'
 pip-check-reqs>=2.5.3; python_version >= '3.12'
-
-# Indirect dependencies are not specified in this file unless constraints are needed.

minimum-constraints-install.txt

@@ -1,13 +1,11 @@
 # Pip constraints file for install dependencies.
 #
-# This file specifies constraints that define the minimum versions of any
-# direct and indirect dependent packages for installation and development of
-# the project.
-# They are used when setting up test environments with the minimum versions of
-# any dependent packages.
+# This file specifies constraints that match the minimum versions specified in
+# the requirement files for install. They are used for example when setting up
+# test environments with the minimum versions of any dependent packages.
 
 
-# Dependencies for installation with Pip (must be installed in a separate pip call)
+# Base dependencies
 
 # For the base packages, we use the versions from Ubuntu 18.04 as a general
 # minimum, and then increase it to the first version that introduced support
@@ -75,7 +73,7 @@ pytz==2019.1; python_version >= '3.10'
 zhmcclient==1.13.3
 
 
-# Indirect dependencies for install (must be consistent with requirements.txt)
+# Indirect dependencies for install that are needed for some reason (must be consistent with requirements.txt)
 
 # Jinja2 is used by ansible/ansible-core and by ansible-doc-extractor.
 Jinja2==2.10.1; python_version <= '3.7'
@@ -104,3 +102,8 @@ jsonschema==4.10.0; python_version >= '3.7'
 urllib3==1.26.18; python_version == '2.7'
 urllib3==1.26.9; python_version == '3.5'
 urllib3==1.26.18; python_version >= '3.6'
+
+
+# All other indirect dependencies for install that are not in requirements.txt
+
+# None

minimum-constraints.txt

@@ -1,15 +1,19 @@
-# Pip constraints file for install and development.
+# Pip constraints file for install and development dependencies.
 #
-# This constraints file specifies constraints that match the minimum versions
-# specified in the requirements files for install and development. The reason
-# for this approach is that in the CI systems, we want to be able to test with
-# the minimum package versions in order to catch any incorrect minimum versions.
+# This file specifies constraints that match the minimum versions specified in
+# the requirement files for install and development. They are used for example
+# when setting up test environments with the minimum versions of any dependent
+# packages.
 
 
+# Note: The included file is processed by Pip but ignored by the Safety tool.
+# Thus, safety with the 'all' profile actually only checks development packages,
+# but that's ok since the 'install' profile checks the install packages.
 -c minimum-constraints-install.txt
 
 
-# Direct dependencies for development (must be consistent with dev-requirements.txt)
+# Direct dependencies for development and indirect dependencies for development
+# that are needed for some reason (must be consistent with dev-requirements.txt)
 
 # Ansible validate-modules (no imports, invoked via validate-modules script)
 mock==2.0.0
@@ -134,7 +138,8 @@ pip-check-reqs==2.3.2; python_version >= '3.5' and python_version <= '3.7'
 pip-check-reqs==2.4.3; python_version >= '3.8' and python_version <= '3.11'
 pip-check-reqs==2.5.3; python_version >= '3.12'
 
-# Indirect dependencies (not in requirements.txt or dev-requirements.txt)
+
+# Indirect dependencies for development that are not in dev-requirements.txt
 
 alabaster==0.7.9
 attrs==18.2.0; python_version <= '3.9'

requirements.txt

@@ -1,13 +1,10 @@
-# Pip requirements file for installation of the project.
-#
-# The order of packages is significant, because pip processes them in the order
-# of appearance.
-#
-# Make sure that the minimum versions required in this file are consistent with
-# the minimum versions specified in minimum-constraints.txt.
+# Pip requirements file for install dependencies.
 
+# Note: The dependencies in this file will become the dependencies stated
+# in the Ansible collection package metadata.
 
-# Direct dependencies (except pip, setuptools, wheel):
+
+# Direct dependencies for install (must be consistent with minimum-constraints-install.txt)
 
 # Keep minimum versions consistent with table for 'minimum' packages in development.rst and with minimum-constraints.txt
 # Starting with Python 3.9, ansible >=4 is needed.
@@ -48,7 +45,8 @@ pytz>=2016.10
 # zhmcclient @ git+https://github.com/zhmcclient/python-zhmcclient.git@master
 zhmcclient>=1.13.3
 
-# Indirect dependencies are not specified in this file, unless needed to solve versioning issues:
+
+# Indirect dependencies for install that are needed for some reason (must be consistent with minimum-constraints-install.txt)
 
 # Jinja2 is used by ansible/ansible-core and by ansible-doc-extractor.
 # The module.rst.j2 template used by ansible-doc-extractor uses the 'tojson' filter added in Jinja2 2.9