From f75e2ef217565323e9d4a17895aa2d4e2da7fe1a Mon Sep 17 00:00:00 2001
From: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Date: Sun, 8 Nov 2020 10:45:04 +0100
Subject: [PATCH] doc: desc. 'loaded' sym in NEWS/MIGRATING

---
 MIGRATING.rst | 22 ++++++++++++++++++++++
 NEWS.rst      |  3 +++
 2 files changed, 25 insertions(+)

diff --git a/MIGRATING.rst b/MIGRATING.rst
index 0950b27e..ca7ac279 100644
--- a/MIGRATING.rst
+++ b/MIGRATING.rst
@@ -45,6 +45,28 @@ The :mfvar:`ModuleTool` and :mfvar:`ModuleToolVersion` variables and the
 :mfcmd:`versioncmp` modulefile command are supported by the `Lmod`_ project
 starting version ``8.4.8``.
 
+Symbolic version to designate module loaded version
+---------------------------------------------------
+
+When the `Advanced module version specifiers`_ is enabled, the ``loaded``
+symbolic version may be used to designate the currently loaded version of
+specified module.
+
+.. code-block:: console
+
+    $ ml display foo@loaded
+    -------------------------------------------------------------------
+    /path/to/modulefiles/foo/1.0:
+    
+    module-whatis   foo/1.0
+    -------------------------------------------------------------------
+
+If no version of specified module can be found loaded, an error is returned.
+
+.. code-block:: console
+
+    $ ml display foo@loaded
+    ERROR: No loaded version found for 'foo' module
 
 From v4.5 to v4.6
 =================
diff --git a/NEWS.rst b/NEWS.rst
index da2c0d87..8a885ed3 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -57,6 +57,9 @@ Modules 4.7.0 (not yet released)
 * Remove the pre-definition of runtime states with no specific property. These
   basic states are defined on-the-fly which implied they are not reported on a
   :subcmd:`module config --dump-state<config>` command unless if instanciated.
+* Introduce the ``loaded`` symbolic version among advanced version specifiers
+  (e.g. ``foo@loaded``) to designate the currently loaded version of specified
+  module. (fix issue #366)
 
 
 .. _4.6 release notes: