From 606e99d686143223c746a1e5cb7eee23652d0a82 Mon Sep 17 00:00:00 2001
From: Daniel Mach <dmach@redhat.com>
Date: Aug 15 2017 11:24:28 +0000
Subject: Document naming policy.


---

diff --git a/source/development/building-modules.rst b/source/development/building-modules.rst
index 0ae9661..d523a70 100644
--- a/source/development/building-modules.rst
+++ b/source/development/building-modules.rst
@@ -7,6 +7,7 @@ Building Modules
     :maxdepth: 1
 
 
+    building-modules/naming-policy
     building-modules/developing
     building-modules/module-guidelines
     building-modules/building-local
diff --git a/source/development/building-modules/naming-policy.rst b/source/development/building-modules/naming-policy.rst
new file mode 100644
index 0000000..3944ca3
--- /dev/null
+++ b/source/development/building-modules/naming-policy.rst
@@ -0,0 +1,112 @@
+=============
+Naming Policy
+=============
+This document defines naming policy for modulemd metadata of final (built) modules.
+This policy does **NOT** apply on sources such as modulemd yaml in dist-git.
+
+The goal is to provide unique identifiers for modules
+that are both human readable and also suitable for machine processing.
+
+
+Fields
+------
+
+* **N** - Name
+* **S** - Stream
+* **V** - Version
+* **C** - Context
+* **A** - Arch
+* **P** - Profile
+
+
+Separators
+----------
+| Fields are separated with ':' (colon): N:S:V:C:A.
+| If P is specified, it's separated from N:S:V:C:A with '/' (forward slash): N:S:V:C:A/P.
+
+Examples::
+
+    # N:S:V:C:A
+    base-runtime:fedora-26:1:0123abcd:x86_64
+
+    # N:S:V:C:A/P
+    base-runtime:fedora-26:1:0123abcd:x86_64/minimal
+
+
+Forms
+-----
+A form is a sequence of fields that fully or partially identifies a module.
+
+
+Full Forms
+~~~~~~~~~~
+
+N:S:V:C:A
+    Unique identifier of a module.
+N:S:V:C:A/P
+    Unique identifier of a module profile.
+
+
+Partial Forms
+~~~~~~~~~~~~~
+
+Supported partial forms are: N [ : S [ :V [ :C ] ] ] [ :A ] [ /P ]
+
+Namely:
+
+* N
+* N::A
+* N:S
+* N:S::A
+* N:S:V
+* N:S:V::A
+* N:S:V:C
+* N:S:V:C:A (identical to N:S:V:C::A)
+* and all combinations with /P
+
+Missing fields **SHOULD** be populated with recommended defaults:
+
+Stream
+    defaults to the enabled or system default stream for the module in this particular order
+Version
+    defaults to the latest available version in the module stream
+Context
+    defaults to a value matching with already installed modules or modules involved in the transaction (not yet installed)
+Arch
+    defaults to the system arch (e.g. DNF's $basearch)
+Profile
+    defaults to the system default or 'default' profile
+
+
+Allowed Characters
+------------------
+**N** - Name
+    a-z A-Z 0-9 . - _ +
+**S** - Stream
+    a-z A-Z 0-9 . - _ +
+**V** - Version
+    0-9
+**C** - Context
+    0-9 a-f
+**A** - Arch
+    a-z A-Z 0-9 . - _ +
+**P** - Profile
+    a-z A-Z 0-9 . - _ +
+
+All fields **MUST** start and end with an alphanumeric character:
+a-z A-Z 0-9
+
+
+Forbidden Characters
+--------------------
+This paragraph serves as a design decision for future changes.
+
+Following characters **MUST NOT** be part of any field:
+
+* ':' (colon) - separator
+* '/' (forward slash) - profile separator
+* '\\\\' (backslash) - comon control character
+* '*' (asterisk) - common wildcard
+* '?' (question mark) - common wildcard
+* '@' (at) - grpspec in YUM and DNF
+* ' ' (space) - common separator