doc: change approach with version req in cache file magic cookie

Signed-off-by: Xavier Delaruelle <[email protected]>

Author: xdelaruelle

NEWS.rst

@@ -139,6 +139,11 @@ Modules 5.6.0 (not yet released)
   containing newline character. Exception is made for *csh* and *tcsh* shells
   where newline characters are chopped from value. (fix issue #557)
 * Sort modules in JSON output as done on regular output.
+* :subcmd:`cachebuild` command now sets the minimal Modules version specified
+  in the cache file magic cookie header to the oldest Modules version
+  compatible with this cache file, rather than the version that generated the
+  cache file. Freshly generated cache files are compatible with Modules 5.3
+  and above.
 
 .. _Security policy: https://github.com/envmodules/modules/blob/main/SECURITY.md
 .. _Modules chat room: https://matrix.to/#/#modules:matrix.org

doc/source/changes.rst

@@ -1009,6 +1009,12 @@ The following module sub-commands appeared on Modules 5.
  module specification is provided as argument or if :file:`.modulecache` file
  is specifically linted.
 
+:subcmd:`cachebuild`
+
+ Starting Modules 5.6, the minimal Modules version specified in the cache file
+ header indicates the oldest Modules version compatible with this cache file
+ (5.3), rather than the version that generated the cache file.
+
 Environment
 """""""""""
 

doc/source/design/module-cache.rst

@@ -183,6 +183,9 @@ used or not if only a subset of elements is recorded.
 Cache validity
 --------------
 
+From Modules 5.3 to 5.5
+^^^^^^^^^^^^^^^^^^^^^^^
+
 Cache file header indicates a Modules version number. It corresponds to the
 Modules version:
 
@@ -197,6 +200,35 @@ upgraded to a newer minor version (for instance from 5.3 to 5.4):
 * better to ensure cache file is accurate for the Modules version as modulerc
   and modulefile commands may evolve from one version to another
 
+Starting Modules 5.6
+^^^^^^^^^^^^^^^^^^^^
+
+Approach to cache validity is changed on Modules 5.6 to cover use cases where
+different Modules installation uses the same set of modulepaths. This is for
+instance the case when a service provides modulepaths with cache files in them
+and just requires a minimal version of Modules. Or on a computing center, when
+the same modulepaths are used by different supercomputers which may use
+different version of Modules at some point in time.
+
+With this change the cache file header still indicates a Modules version
+number. But this version number now corresponds to the minimal Modules version
+able to use this cache file.
+
+With such change, backward compatibility is expected on module cache Tcl
+commands. Addition of new commands will lead to an increase of the minimal
+version required. Argument change to existing command is not possible, only
+the introduction of optional argument will be ok (with increase of minimal
+version required).
+
+When generating cache file, minimal version required is set back to ``5.3`` as
+no change occurred on the cache file format since the introduction of the
+cache feature.
+
+As minimal Modules version check code is the same for cache file than for
+modulefile since the introduction of the cache feature, cache file has always
+been taken into account as soon as the Modules version matches the minimal
+requirement.
+
 Cache usage
 -----------