Clarified comments in constraints/requirements files

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

base-requirements.txt

@@ -1,11 +1,5 @@
 # Pip requirements file for base packages for a Python env.
-#
-# The order of packages is significant, because pip processes them in the order
-# of appearance. Changing the order has an impact on the overall integration
-# process, which may cause wedges in the gate later.
 
-# Make sure that the package versions in minimum-constraints.txt are also
-# the minimum versions required in requirements.txt and dev-requirements.txt.
 
 # Base dependencies (must be consistent with minimum-constraints.txt)
 

dev-requirements.txt

@@ -1,16 +1,13 @@
 # Pip requirements file for development dependencies.
-#
-# The order of packages is significant, because pip processes them in the order
-# of appearance. Changing the order has an impact on the overall integration
-# process, which may cause wedges in the gate later.
 
-# Make sure that the package versions in minimum-constraints.txt are also
-# the minimum versions required in requirements.txt and dev-requirements.txt.
 
-
-# Runtime dependencies:
+# Include install dependencies
 -r requirements.txt
 
+
+# Direct dependencies for development and indirect dependencies for development
+# that are needed for some reason (must be consistent with minimum-constraints.txt)
+
 # six
 # tox 3.17 requires six>=1.14.0 (tox 4.0 no longer uses six)
 # zhmcclient 1.11 requires six>=1.14.0 up to py39 and six>=1.16.0 from py310 on

minimum-constraints-install.txt

@@ -1,9 +1,8 @@
-# Pip constraints file for install.
+# Pip constraints file for install dependencies.
 #
-# This constraints file specifies constraints that match the minimum versions
-# specified in the requirements files for install. 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. They are used for example when setting up
+# test environments with the minimum versions of any dependent packages.
 
 # Make sure that the package versions in minimum-constraints.txt are also
 # the minimum versions required in requirements.txt and dev-requirements.txt.
@@ -56,10 +55,13 @@ yamlloader==0.5.5
 # urllib3 is used to disable warnings
 urllib3==1.26.18
 
+
+# Indirect dependencies for install that are needed for some reason (must be consistent with requirements.txt)
+
 pyrsistent==0.15.1
 
 
-# Indirect dependencies for install (must be consistent with requirements.txt)
+# All other indirect dependencies for install that are not in requirements.txt
 
 certifi==2023.07.22
 chardet==3.0.3

minimum-constraints.txt

@@ -1,18 +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
-
-# Make sure that the package versions in minimum-constraints.txt are also
-# the minimum versions required in requirements.txt and dev-requirements.txt.
+# 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)
 
 # six (only needed by packages that still support Python 2)
 six==1.14.0; python_version <= '3.9'
@@ -123,7 +124,8 @@ pip-check-reqs==2.3.2; python_version >= '3.6' 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.1; python_version >= '3.12'
 
-# Indirect dependencies for development (must be consistent with dev-requirements.txt)
+
+# Indirect dependencies for development that are not in dev-requirements.txt
 
 alabaster==0.7.9
 appdirs==1.4.3

requirements.txt

@@ -1,13 +1,10 @@
-# Pip requirements file for zhmccli runtime dependencies.
-#
-# The order of packages is significant, because pip processes them in the order
-# of appearance. Changing the order has an impact on the overall integration
-# process, which may cause wedges in the gate later.
+# Pip requirements file for install dependencies.
 
-# Make sure that the package versions in minimum-constraints.txt are also
-# the minimum versions required in requirements.txt and dev-requirements.txt.
+# Note: The dependencies in this file will become the dependencies stated
+# in the Pypi package metadata.
 
-# Direct dependencies (except pip, setuptools, wheel):
+
+# Direct dependencies for install (must be consistent with minimum-constraints-install.txt)
 
 # zhmcclient @ git+https://github.com/zhmcclient/python-zhmcclient.git@stable_1.13
 zhmcclient>=1.13.4
@@ -44,7 +41,7 @@ yamlloader>=0.5.5
 urllib3>=1.26.18
 
 
-# Indirect dependencies that need to be adjusted for some reason:
+# Indirect dependencies for install that are needed for some reason (must be consistent with minimum-constraints-install.txt)
 
 # pyrsistent is used by jsonschema 3.x (no longer by jsonschema 4.x)
 pyrsistent>=0.15.1