doc: desc. module-warn in MIGRATING

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

Author: xdelaruelle

MIGRATING.rst

@@ -33,6 +33,32 @@ commands (:subcmd:`avail`, :subcmd:`list` and :subcmd:`spider`).
 When set, this is equivalent to always adding the :option:`--all` command-line
 option.
 
+Issue warning upon module evaluation
+------------------------------------
+
+The mfcmd:`module-warn` modulefile Tcl command is introduced to define warning
+message to print when loading specified modulefiles.
+
+.. parsed-literal::
+
+    :ps:`$` cat /path/to/modulefiles/foo/1.0
+    #%Module
+    module-warn --message {Please consider using "bar" module instead} foo
+    :ps:`$` module load foo
+    Loading :sgrhi:`foo/1.0`
+      :sgrwa:`WARNING`: Please consider using "bar" module instead
+
+The warning message is printed when targeted modulefile is evaluated in
+*load*, *display*, *help* or *test* mode.
+
+:mfcmd:`module-warn` supports the same kind of options than
+:mfcmd:`module-tag` or :mfcmd:`module-hide`: it is possible to specify a list
+of affected or unaffected users or groups. Warning may also be only effective
+before or after a particular date.
+
+The ``warning`` tag is set on modules targeted by a mfcmd:`module-warn`
+command.
+
 
 v5.5
 ====

doc/source/design/module-warn.rst

@@ -4,7 +4,7 @@ module-warn modulefile command
 ==============================
 
 This design document describes the :mfcmd:`module-warn` Tcl command that emits
-warning message when targeted module is loaded.
+warning message when targeted module is evaluated.
 
 Need for such command comes from `EESSI`_ software-layer where a warning
 message is printed when loading modules if a file is not found.