PR#1705: Add a short doc on module naming

Merges #1705
https://pagure.io/fm-orchestrator/pull-request/1705

docs/MODULE_NAMING.rst

@@ -0,0 +1,97 @@
+Module Naming
+=============
+
+The goal of this document is to clarify how modules are named in MBS.
+
+For a more detailed overview of the build process, see |docs/HOW_MBS_BUILDS_MODULES.rst|_.
+
+.. |docs/HOW_MBS_BUILDS_MODULES.rst| replace:: ``docs/HOW_MBS_BUILDS_MODULES.rst``
+.. _docs/HOW_MBS_BUILDS_MODULES.rst: HOW_MBS_BUILDS_MODULES.rst
+
+
+Modularity Naming Practices
+---------------------------
+
+Modularity adopted a naming scheme that was similar to, yet confusingly
+different from, the RPM naming scheme.
+An individual binary module is given an NSVCA identifier, where these letters
+stand for name, stream, version, context, and architecture.
+
+It may be helpful to review the
+`Modularity documentation <https://docs.fedoraproject.org/en-US/modularity/architecture/nsvca/>`_.
+
+In MBS, a given module build is a set of binary modules with the same NSVC, but
+varying architectures.
+So, in MBS we refer to these builds by NSVC (or by their numeric module id).
+
+MBS requires that NSVC values are unique across the system.
+Collisions are typically avoided because MBS determines the version and context
+automatically from the SCM.
+In cases where an NSVC collision is encountered, a common solution is to
+simply add a new (possibly empty) commit in the SCM.
+
+
+Where the name comes from
+-------------------------
+
+The different parts of the NSVC are controlled in different ways.
+Most can be set in the modulemd file, but might also be determined by
+MBS.
+
+**Name**
+
+The name is often specified in the modulemd file, but MBS can also
+determine it from the SCM name.
+Unless the ``allow_name_override_from_scm`` setting is enabled, MBS will
+error if the modulemd specifies a name value that does not match the SCM name.
+
+**Stream**
+
+Similarly, the stream can be set in the modulemd or determined from the SCM.
+
+MBS determines the stream from the SCM branch.
+If the ``allow_dashes_in_svc`` setting is False (the default), then any dashes
+in the branch name are converted to underscores when determining the stream.
+
+If the ``allow_stream_override_from_scm`` setting is not enabled, then MBS will
+error if the modulemd specifies a stream that does not match the one determined
+by the SCM.
+
+**Version**
+
+The version is generated by MBS from the commit time.
+Setting the version in the modulemd is not allowed and MBS will error.
+
+**Context**
+
+By default, the context is generated by MBS.
+However, it is possible to specify a static context in the modulemd.
+This is covered in |docs/STATIC_CONTEXTS.rst|_.
+
+.. |docs/STATIC_CONTEXTS.rst| replace:: ``docs/STATIC_CONTEXTS.rst``
+.. _docs/STATIC_CONTEXTS.rst: STATIC_CONTEXTS.rst
+
+For scratch module builds, MBS appends a counter to the context to ensure
+uniqueness.
+
+
+Mapping names into Koji
+-----------------------
+
+When module builds are imported into Koji, they must be given an NVR
+(name, version, release).
+MBS determines this from the NSVC as follows:
+
+* The name for the Koji build is the same as the name for the module build.
+* The version for the Koji build is the **stream** value for the module build
+  (i.e. not the version), with any dashes replaced by underscores
+* The release for the Koji build is a combination of the version and context
+  for the module build, separated by a dot
+
+Because of the transformation of the stream value, it can be complicated to map
+back to an NSVC from an NVR.
+Any tools that need to perform this reverse mapping should be aware of the
+possible dash replacement.
+The most accurate way to map back to a module build from a Koji build is to
+read the ``typeinfo.module.module_build_service_id`` field that MBS places
+in build.extra at import time.