Modularity Naming Guidelines

Each module has a name, and one or more streams that usually represent a major version of the application, language stack, or other software in the module. To simplify their installation, modules can define profiles representing a specific use case. Modules are built out of SRPM packages that have a name and one or more branches.

Example 1: A Node.js module could be named "nodejs", with three streams "6", "8" and "10", and two profiles "default" and "devel". This module would include a single package in each stream named "nodejs", branched as "6", "8", and "10".

Example 2: Another one, PostgreSQL, could be named as "postgresql", its two streams could be "9.6" and "10", because that’s where the upstream compatibility is, and its profiles could include "client" and "server". Both streams could be built out of two packages. One named "postgresql", having branches "9.6" and "10", which would be the main package; and another one named "python-pgsql", having a single branch "latest", which would always bind to the right version of the database during build, and would provide Python bindings.

Module name

A module usually represents an application, a language stack, or any other logical collection of packages. Module name should represent the name of the software it ships. Using lowercase, hyphen-separated names is preferable. Some examples could include "nodejs", "golang", "golang-ecosystem", or "cri-o".

A module name maps to its repository name in DistGit.

Module stream name

The module stream name is assigned by creating a branch of that name in DistGit and building from it. The Module Build Service will automatically set the stream name of the resulting module to match.

Option 1: Major version

A stream usually represents a major version of the software, and should follow the versioning of the major upstream component included in the module. Consideration should be given to the upstream community’s adherence to API (or even ABI) stability on the versions of their software. In other words, some communities will maintain stability on the X branch, many the Y branch, and some even the Z branch. As a result, the branch names should reflect that stability. For example, most communities are stable on the Y branch so the branch name should be "X.Y". (e.g. mariadb:10.2) included in the module.

Compatibility on non-technical factors should be also considered. For example, a package that maintains exactly the same API but has a significant visual and UX overhaul probably belongs in a new stream. Or to put it another way, human interaction is an interface too.

Option 2: CalVer

If your module is a "collection of items" with no primary piece of software (e.g. container-tools), the versioning scheme should use the CalVer (http://calver.org/) scheme with YYYY.MINOR where the YYYY is the year of the release and MINOR version is an integer starting at 0. In other words, if I released a system-tools module in November of 2017 we would expect to see 2017.0. My next release, in May of 2018, which does not break ABI/API, is also 2017.0. However, in October of 2018 we want to introduce a new stream so we name it 2018.0. The month is omitted as ideally these modules won’t be breaking API/ABI more than once a year.

Option 3: Rolling and unstable streams

For streams that don’t guarantee an API/ABI stability over time and just roll forward, we suggest packagers use one of the following stream names.

  • "rolling" for user-focused content meant for general use

  • "unstable" for pre-release content or content in active development meant for preview and testing rather than general use

We mandate a good use of the description and/or summary field to clearly state what this particular stream represents.

This policy doesn’t enforce changes in existing branch names, however, packagers are welcome to do so in order to bring more consistency to the distribution.

Option 4: Upstream conventions

In case there are well-established upstream conventions, using them is also a good option.

Again, especially in this case, we mandate a good use of the description and/or summary field to clearly state what this particular stream represents.

Module profile name and description

Profiles make installation easier by giving the user some predefined package groups that represent a common installation for a specific use case. Profiles have name and a description — using both is mandatory.

Profile name should be a one word that best represent the use case. Some examples could include "client" or "server" for database modules, "default" or "devel" for language runtime modules, but also "minimal" and others. There some reserved profile names for specific purposes e.g. setting up a buildroot. Please see the modulemd spec for a complete list.

Descriptions should be a short summary describing the profile. Including it is important especially for potential translations, as profile names won’t be translated.

Unified profile names

In some cases, there are many suitable alternatives for for one meaning i.e. "dev", "devel", and "development". We believe that choosing one that would be consistently used across all modules that need such profile would lead to a better user experience. The ones identified are listed below:

  • "default" a default profile for a "standard" installation, should the module have something like this

  • "devel" for development-related profiles

  • "client" only the client component of a piece of software (e.g. database client)

  • "server" only the server component of a piece of software (e.g. database server)

Package name

No changes for package names with Modularity. Please refer to the official Guidelines for Naming Fedora Packages.

Package branch name

Packages included in modules should be branched in a similar manner as modules. So instead of having one branch for release (such as "f27", "f28, etc.), using upstream major versions as branches is recommended. Please read the Module stream name section above for guidance.

The exact branching should be chosen with consideration given to the upstream community’s adherence to API/ABI stability on the versions of their software. In other words, in the context of X.Y.Z style naming, some communities will maintain stability on the X branch, many the Y branch, and some even the Z branch. As a result, the branch names should reflect that stability. For example, most communities are stable on the Y branch so the branch name should be "X.Y". While this rule is focusing on examples using X.Y.Z style naming, CalVer (http://calver.org/), or other versioning schemes, should be faithfully reflected using the same guidance regarding which branches to create.

For "rolling release" projects that don’t change their API/ABI (e.g. Python’s timezone database, pytz) a single "stable" branch is appropriate.