doc: desc. __MODULES_LMSTICKYRULE in changes/man/NEWS

NEWS.rst

@@ -68,6 +68,10 @@ Modules 5.4.0 (not yet released)
   #511)
 * Add ``--glob`` option to :mfcmd:`remove-path` modulefile command in order to
   remove any values in variable matching a glob-style pattern.
+* Record module specification on which loaded module stickiness applies in
+  :envvar:`__MODULES_LMSTICKYRULE` environment variable. It helps to determine
+  if stickiness is satisfied when changing loaded modules. Which was not
+  working correctly for virtual modules. (fix issue #506)
 
 
 .. _5.3 release notes:

doc/source/changes.rst

@@ -950,6 +950,7 @@ The following environment variables appeared on Modules 5.
 | 5.4        | :envvar:`MODULES_STICKY_PURGE`,                                 |
 |            | :envvar:`MODULES_UNIQUE_NAME_LOADED`,                           |
 |            | :envvar:`MODULES_ERROR_ON_MULTI_LOAD`                           |
+|            | :envvar:`__MODULES_LMSTICKYRULE`                                |
 +------------+-----------------------------------------------------------------+
 
 Modules Specific Tcl Commands
@@ -1049,8 +1050,13 @@ The following modulefile Tcl commands appeared on Modules 5.
 
 :mfcmd:`module-tag`, :mfcmd:`module-hide`, :mfcmd:`module-forbid`
 
- Starting version 5.4, module can be specified with its full path file name
- to precisely target one modulefile.
+ Starting with version 5.4:
+
+ * module can be specified with its full path file name to precisely target
+   one modulefile.
+ * module specification on which stickiness applies is recorded in loaded
+   environment to determine if it is still satisfied when updating
+   environment.
 
 Modules Variables
 """""""""""""""""

doc/source/module.rst

@@ -3577,6 +3577,25 @@ ENVIRONMENT
        Variable renamed from ``MODULES_LMSOURCESH`` to
        ``__MODULES_LMSOURCESH``
 
+.. envvar:: __MODULES_LMSTICKYRULE
+
+ A colon separated list of the sticky or super-sticky tag definitions applying
+ to loaded *modulefiles*. Each element in this list starts by the name of the
+ loaded *modulefile* followed by the sticky tag name and the module
+ specifications on which the tag applies. These loaded modulefiles and sticky
+ tag definitions are separated by the ampersand character. Tag name and module
+ specifications on which it applies are separated by the pipe character.
+
+ When stickiness applies specifically to the loaded module name and version,
+ sticky rule is not recorded in ``__MODULES_LMSTICKYRULE``.
+
+ This environment variable is intended for :command:`module` command internal
+ use to get knowledge of the stickiness scope when sticky module is changed.
+
+ .. only:: html
+
+    .. versionadded:: 5.4
+
 .. envvar:: __MODULES_LMTAG
 
  A colon separated list of the tags corresponding to all loaded *modulefiles*