From 1b89aafcaceb732b77d1f403fc124b8ad5174c24 Mon Sep 17 00:00:00 2001
From: Daniel Mach <dmach@redhat.com>
Date: Aug 02 2017 12:34:06 +0000
Subject: Document naming policy.


Signed-off-by: Daniel Mach <dmach@redhat.com>

---

diff --git a/docs/index.rst b/docs/index.rst
index aed2728..dcc5bb7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,30 @@
 modulemd's documentation
 ========================
 
+Contents
+--------
+
+.. toctree::
+    :maxdepth: 1
+
+    naming-policy
+
+
+Python Quickstart
+-----------------
+
 .. automodule:: modulemd
-   :members: none
+    :members: none
+
+
+Python modules
+--------------
+
+.. toctree::
+    :maxdepth: 2
+
+    modulemd
+
 
 Indices and tables
 ==================
diff --git a/docs/naming-policy.rst b/docs/naming-policy.rst
new file mode 100644
index 0000000..bdf210d
--- /dev/null
+++ b/docs/naming-policy.rst
@@ -0,0 +1,92 @@
+=============
+Naming Policy
+=============
+This document defines naming policy for modulemd metadata.
+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
+* **A** - Arch
+* **P** - Profile
+
+
+Forms
+-----
+The most common forms are NSVA and NSVAP.
+
+
+Separators
+----------
+| NSVA fields are separated with ':' (colon): N:S:V:A.
+| If P is specified, it's separated from NSVA with '/' (forward slash): N:S:V:A/P.
+
+Examples::
+
+    # NSVA
+    base-runtime:fedora-26:1:x86_64
+
+    # NSVAP
+    base-runtime:fedora-26:1:x86_64/minimal
+
+
+Allowed Characters
+------------------
+**N** - Name
+    a-z A-Z 0-9 . - _
+**S** - Stream
+    a-z A-Z 0-9 . - _
+**V** - Version
+    0-9
+**A** - Arch
+    a-z 0-9 - _
+**P** - Profile
+    a-z 0-9 -
+
+All fields must start and end with a number or a letter:
+a-z A-Z 0-9
+
+
+Forbidden Characters
+--------------------
+This paragraph serves as a design decision for future changes.
+
+Following characters must never become part of any field:
+
+* ':' (colon) - separator
+* '/' (forward slash) - profile separator
+* '\\' (backslash) - comon control character
+* '*' (asterisk) - common wildcard
+* '?' (question mark) - common wildcard
+* ' ' (space) - common separator
+
+
+File Names
+----------
+Single module metadata records stored on disk must be
+named according to their NSVA.
+Profile must **not** be part of file name
+as it's only an internal metadata detail,
+which is not part of module identity::
+
+    $name:$stream:$version:$arch.modulemd.yaml
+
+
+Example::
+
+    base-runtime:fedora-26:1:x86_64.modulemd.yaml
+
+
+Repomd Repodata
+---------------
+Module metadata in repomd repodata is stored as yaml multi-document.
+It is highly recommended to sort module metadata in this multi-document
+by NSVA to generate predictable and diffable output.
+
+* Mandatory repomd.xml ID: **modules**
+* Recommended file name: **[$hash-]modules.yaml[.$compression]**