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.
