clarify some macro instructions (#385)

Author: james-bruten-mo

source/WorkingPractices/inputs.rst

@@ -89,6 +89,22 @@ to the new metadata. The SSD team are also available to advise on whether an upg
 
   If you have a linked LFRic Core or Jules ticket with metadata changes, you can load their metadata by adding ``-M /path/to/working_copy/rose-meta`` to the ``rose-edit`` command.
 
+
+Adding a new LFRic Metadata Section
+-----------------------------------
+
+Due to the way lfric metadata is shared, if a new LFRic metadata section is added, then a few new files are added. A new LFRic metadata section here is defined as a new directory within an existing or new ``rose-meta`` directory. Adding a new metadata section requires:
+
+* ``rose-meta/META-NAME/HEAD/rose-meta.conf``
+* ``rose-meta/META-NAME/vnX.Y/rose-meta.conf`` (where ``X.Y`` is the most recent released version)
+* ``rose-meta/META-NAME/versions.py``
+* A symlink from the top-level rose-meta directory to the new directory (see existing ones for examples)
+
+The ``vnX.Y`` and ``HEAD`` metadata should be identical for this initial ticket, other than any import statements, which should point at vnX.Y or HEAD respectively. Other ``vnX.Y`` and ``versionAB_CD.py`` files shouldn't be modified or added (these are a snapshot of the metadata at a release).
+
+If a new rose-stem app using the new metadata is also being added, then a "blank" upgrade macro will also need to be added with a ``BEFORE_TAG=vnX.Y`` and a standard ``AFTER_TAG=vnX.Y_tTTTT``. This upgrade macro will allow the new app to be updated to the Head metadata when the branch is merged to trunk. The ``rose-app.conf`` for this app will require a metadata import line of format, ``meta=META-NAME/vnX.Y``.
+
+
 How to add an upgrade macro to your branch
 ------------------------------------------
 

source/WorkingPractices/macros.rst

@@ -123,9 +123,9 @@ To add upgrade macros to LFRic the following steps can be followed:
 
 .. code-block::
 
-    export CYLC_VERSION=8 
+    export CYLC_VERSION=8
 
-    SimSys_Scripts/lfric_macros/apply_macros.py vnXX.Y_tTTTT -a Apps -c Core -j Jules
+    SimSys_Scripts/lfric_macros/apply_macros.py vnX.Y_tZZZZ [--apps=/path/to/apps] [--core=/path/to/core] [--jules=/path/to/jules]
 
 .. important::
 

source/WorkingPractices/metadata_guidance.rst

@@ -3,6 +3,10 @@
 ..
   This section will need some thought and revisiting after CA2 is completed.
 
+.. important::
+
+    Do **not** edit the existing ``vnX.Y`` metadata directories or the upgrade python files (eg ``versionab_cd.py``) as these are a snapshot of the metadata at release. Only the ``HEAD`` and ``versions.py`` files should be modified.
+
 Some basic guidance on Rose metadata
 ====================================