diff --git a/docs/MODULE_NAMING.rst b/docs/MODULE_NAMING.rst new file mode 100644 index 00000000..9d27103b --- /dev/null +++ b/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 `_. + +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.