doc: add "module-warn" design notes

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

Author: xdelaruelle

.hunspell.en.dic

@@ -1219,3 +1219,4 @@ dumpname
 syntaxdbs
 spi
 LMUSE
+EESSI

NEWS.rst

@@ -114,6 +114,7 @@ Modules 5.6.0 (not yet released)
   print when modulefile is evaluated in ``help`` mode.
 * Update :mfcmd:`add-property` modulefile command to use its *value* argument
   to define tag on currently loading module.
+* Doc: add :ref:`module-warn` design notes.
 
 .. _Security policy: https://github.com/envmodules/modules/blob/main/SECURITY.md
 .. _Modules chat room: https://matrix.to/#/#modules:matrix.org

doc/source/design/module-tags.rst

@@ -48,6 +48,7 @@ Specification
   - ``nearly-forbidden``: module that soon cannot be loaded (tag acquired through ``module-forbid``)
   - ``loaded``: loaded module
   - ``auto-loaded``: module automatically loaded by another module
+  - ``warning``: warning message reported on load (tag acquired through ``module-warn``)
 
 - Tags set with ``module-tag`` or ``--tag`` option associated to a specific behavior:
 
@@ -250,7 +251,7 @@ Abbreviations
 
 - The :mconfig:`tag_abbrev` configuration defines the abbreviations to apply to each tag
 
-  - Set by default at configure time to ``auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL``
+  - Set by default at configure time to ``auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL:warning=W``
 
     - Note that by default, *hidden* and *hidden-loaded* tags share the same abbreviation, as they operate on separate contexts (respectively avail and list contexts)
 

doc/source/design/module-warn.rst

@@ -0,0 +1,62 @@
+.. _module-warn:
+
+module-warn modulefile command
+==============================
+
+This design document describes the :mfcmd:`module-warn` Tcl command that emits
+warning message when targeted module is loaded.
+
+Need for such command comes from `EESSI`_ software-layer where a warning
+message is printed when loading modules if a file is not found.
+
+.. _EESSI: https://www.eessi.io/
+
+Command specification
+---------------------
+
+The command has following syntax::
+
+    module-warn [options] --message text modulefile...
+
+When a ``module-warn`` command applies to an evaluated modulefile:
+
+* message is printed as a warning message when targeted module is evaluated in
+  ``load``, ``display``, ``help`` or ``test`` modes.
+* warning message is printed at the end of the modulefile evaluation
+* ``warning`` tag is set on available or loaded module
+
+Like other commands of this kind, modulefile specification accepts advanced
+version specifiers (see
+:ref:`module_version_specification_to_return_all_matching_modules`).
+
+This command is available in modulerc and modulefile evaluation contexts. In
+modulefile context, it could be replaced by :mfcmd:`reportWarning`, but it is
+easier to also enables it in this context to benefit from the options that
+inhibit or enable specifically the warning mechanism.
+
+``module-warn`` accepts options that change warn mechanism:
+
+* ``--not-user``: specify a list of unaffected users
+* ``--not-group``: specify a list of groups whose member are unaffected
+* ``--user``: specify a list of users specifically affected
+* ``--group``: specify a list of groups whose member are specifically affected
+* ``--before``: enables warn mechanism until a given date
+* ``--after``: enables warn mechanism after a given date
+* ``--message``: warning message to print
+
+``warning`` tag
+---------------
+
+``warning`` tag is introduced to visibly catch modulefiles affected by
+``module-warn``:
+
+* ``W`` is the abbreviation for this tag
+* ``W=30;43`` and ``W=103`` is respectively added to dark and light color
+  palettes (same as nearly-forbidden modules)
+* This tag is recorded into collections following standard tag recording
+  mechanism
+* This tag cannot be set manually with ``module-tag`` command
+* If ``module-warn`` is used within modulefile, extra match search will not
+  find ``warning`` tag of these modules
+
+.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: