Fedora Packaging Guidelines for Modules

Disclaimer

Note that this document is just a draft. These aren't official, approved Fedora guidelines. Neither is the modulemd format finalized with which we're working with here.

Overview

The goal of this document is to describe how to create valid module files, document purposes of all the data fields in them, hint best practices and demonstrate some examples.

Each module is defined by a single YAML file and comprises of a number of key-value pairs describing the module's properties and components it contains. Not everything needs to (or even should) be filled in by the module packager; some of the fields get populated later during the module build or distribution phase. The module file format is commonly known as modulemd.

The original format specification can be found in the modulemd repository.

Required fields

Document header and the data section

Every modulemd file MUST contain a modulemd document header which consists of the document type tag and the document format version, and a data section holding the module data.

 document: modulemd
 version: 0
 data:
     (...)

The version is an integer and is not currently used for anything; this will change later in the modulemd development phase.

Module name

Every module MUST define its name. The format isn't strictly defined yet but will most likely follow the format of SRPM names.

 name: example

Note that unlike srpms/rpms the name of the module doesn't define the line-of-upgrade, on it's own. In the packaging world the name is the means by which you upgrade, to get bugfixes etc. In the modular world you can still only have a single module named "foo" but depending on your configuration your machine will only use certain versions of those modules.

Module version and release

Every module MUST also specify its version and release. The format is similar to that for packaging, but the meaning is very different. In the packaging world the version is taken from upstream, and the release is taken from the distribution starting at 1 and incremented as changes happen. In the modular world the version represents the rpm data for the module, and the release represents the metadata within the module. Currently the plan is to have a date, hash and id for the version. However because of the line-of-upgrade differences, sorting should not be assumed in the same way it is in the packaging world.

 version: 20161201T1301Z.d41d8cd98f00b204e9800998ecf8427e.1.23
 release: 20161201T1301Z.68b329da9893e34099c7d8ad5cb9c940

The version field SHOULD be suffixed with the version of the main module component rpm version, where applicable. For example a webserver module that contains the httpd-2.4.18 webserver as its key component should use 2.4.18 as the suffix on it's version. If this cannot be done, you SHOULD drop the suffix and just have a date and hash. The hash MUST be generated in a reproducible way from the contents of the rpms within the module.

The release field hash MUST be generated in a reproducible way from the data within the module file, so that if any data within the module changes the hash will change (and if it changes back the hash will change back). Obviously this has to ignore the release field.

Module summary and description

Every module MUST include human-readable short summary and description. Both should be written in US English.

 summary: An example module
 description: >
     An example long description of an example module, written just
     to demonstrate the purpose of this field.

The summary is a one sentence concise description of the module and SHOULD NOT end in a period.

The description expands on this and SHOULD end in a period. Description SHOULD NOT contain installation instructions or configuration manuals.

Module licensing

Every module MUST contain a license section and declare a list of the module's licenses. Note these aren't the module's components' licenses.

 license:
     module:
         - MIT

Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. Therefore MIT might be a reasonable default for most module authors as well.

See Fedora_Packaging_Guidelines_for_Modules#Module_content_licensing to see how to declare components' licenses.

Optional fields

Module content licensing

If the module includes some RPM or non-RPM content, the packager MAY also define a list of content licenses.

 license:
     module:
         - MIT
     content:
         - GPL+
         - BSD

Not every module includes packages and therefore doesn't necessarily have to include this field.

Furthermore, the content licenses list should ideally be automatically filled by module build tools rather than the module author.

Module dependencies

Modules MAY depend on other modules. These module relationships are listed in the depepdencies section.

Note: This section may change significantly in the future.

 dependencies:
     buildrequires:
         example-build-dependency: 20161201T1301Z.d41d8cd98f00b204e9800998ecf8427e.1.23-20161201T1301Z.68b329da9893e34099c7d8ad5cb9c940
     requires:
         example-runtime-dependency: 20161102T1401Z.d41d8cd98f00b204e9800998ecf8427e-20161102T1401Z.68b329da9893e34099c7d8ad5cb9c940

So far modulemd supports two kinds of dependencies:

• buildrequires for listing build dependencies of the module, i.e. modules that define the buildroot for building the module's components
• requires for listing runtime dependencies of the module, i.e. modules that need to be available on the target system for this module to work properly

Both these sections contain key-value pairs where keys are the required module names and values the minimum required version in the version-release format.

Either or both of these sections may be omitted.

Extensible module metadata block

Modules MAY also contain an extensible metadata block, a list of vendor-defined key-value pairs.

 xmd:
     user-defined-key: 42
     another-user-defined-key:
         - the first value of the list
         - the second value of the list

Module references

Modules MAY define links referencing various upstream resources, such as community website, project documentation or upstream bug tracker.

 references:
     community: http://www.example.com/
     documentation: http://www.example.com/docs/1.23/
     tracker: http://www.example.com/bugs/

Module components

Modules MAY, and most modules do contain a components section defining the module's content.

 components:
     (...)

RPM content

Module RPM content is defined in the rpms subsection of components and typically consists of one or more packages described by their SRPM names and additional extra key-value pairs, some required and some optional, associated with them.

Besides packages the rpms section MAY also define the following keys:

• the dependencies switch which controls whether RPM-level dependencies should be automatically included, or bundled, in the module if none of the modules required at runtime would provide these dependencies; this defaults to False and the value cannot be overridden for production module builds in Fedora.
• the api list of RPM binary package names that are considered the stable module API, i.e. supported RPM components of this module that shouldn't break or disappear without a notice; binary RPM packages not listed here are considered internal details and other modules SHOULD NOT depend on them or even expect them to be shipped. Modules with RPM content SHOULD define some RPM module API.
• the filter list of RPM binary packages that should NOT be included. If there is a hard requirement on one of the packages in the filter list, the package will get installed regardless of the filter. filter default is no package will be filtered.

 components:
     rpms:
         dependencies: False
         api:
             - foo
             - foo-devel
         filter:
             - foo-subpackage_1
             - foo-subpackage_2
         packages:
             foo:
                 rationale: The key component of this module
                 commit: abcdef1
                 repository: git://git.example.com/foo.git
                 cache: http://www.example.com/lookasidecache/
                 arches:
                     - i686
                     - x86_64
                 multilib:
                     - x86_64

The following key-value pairs extend the SRPM name:

• rationale - every component MUST declare why it was added to the module; this is currently a free form string and might change in the future.
• commit - the git hash or other commit ID in the repository that should be built and included in this module; recommended. If not defined, the current HEAD or equivalent is used and the hash or other commit ID is recorded in the module by module build tools. So, for example, if we're looking at the commit for the Fedora httpd package, the git hash should come from the official Fedora httpd package repo.
• repository - specifies git or other VCS repository to use as the component's source; in Fedora, dist-git is used and this option cannot be overridden.
• cache - points to RPM lookaside cache; in Fedora this option cannot be overriden.
• arches - a list of architectures this component should be built for; defaults to all available architectures.
• multilib - a list of architectures where this component should be available as multilib, e.g. if x86_64 is listed, x86_64 repositories will also include i686 builds. Defaults to no multilib.

Non-RPM content

Non-RPM content isn't currently supported.

Module profiles

The module author MUST define lists of packages that would be installed by default, and a minimum, when the module is enabled and the particular profile is selected. Whether the packages actually get installed depends on the user's configuration. It is possible to define a profile that doesn't install any packages.

Profile names are arbitrary strings. There are currently two special-purpose profile names defined — default, and minimal. More special-purpose profile names might be defined in the future.

The default profile lists packages that would be installed unless the user's configuration dictates otherwise.

The minimal profile lists packages that would be installed for minimal full functionality of the module, this profile is also used by QA. It's fine if this profile is identical to the default profile. It's fine if other profiles have less packages than this profile, if you which to have partial functionality (for example).

In the case of RPM content, the profile package lists reference binary RPM package names. Non-RPM content isn't currently supported.

 profiles:
     default:
         rpms:
             - myapplication
             - myapplication-plugins
     minimal:
         description: >
             Minimal profile installing only the myapplication package.
         rpms:
             - myapplication

Examples

Minimal module

A minimal module example-1.23-1, containing no packages, having no dependencies whatsoever and defining only the minimal set of required metadata.

 document: modulemd
 version: 0
 data:
     name: example
     version: 20161201T1301Z.d41d8cd98f00b204e9800998ecf8427e
     release: 20161201T1301Z.68b329da9893e34099c7d8ad5cb9c940
     summary: An example summary
     description: >
         An example description.
     license:
         module:
             - MIT

Minimal module with RPM content

A minimal module, example-1.23-1, containing one RPM package with SRPM name foo. This module doesn't define any dependencies or optional metadata.

 document: modulemd
 version: 0
 data:
     name: example
     version: 20161201T1301Z.d41d8cd98f00b204e9800998ecf8427e.1.23
     release: 20161201T1301Z.68b329da9893e34099c7d8ad5cb9c940
     summary: An example summary
     description: >
         An example description.
     license:
         module:
             - MIT
     components:
         rpms:
             packages:
                 foo:
                     rationale: An example RPM component

Minimal module with RPM content but with the -docs subpackage excluded

A minimal module, example-nodoc-1.23-1, containing one RPM package with SRPM name foo. A build of 'foo' creates binary packages 'foo-1.0-1' and the subpackage 'foo-doc-1.0-1'. Both would get included in the module when no filter would be used. This module doesn't define any dependencies or optional metadata.

 document: modulemd
 version: 0
 data:
     name: example
     version: 20161201T1301Z.d41d8cd98f00b204e9800998ecf8427e.1.23
     release: 20161201T1301Z.68b329da9893e34099c7d8ad5cb9c940
     summary: An example summary
     description: >
         An example description.
     license:
         module:
             - MIT
     components:
         rpms:
             packages:
                 foo:
                     rationale: An example RPM component
             filter:
                 - foo-doc

Minimal module with dependencies only (stack)

A minimal module, example-stack-1.23-1, containing no packages or any optional metadata besides dependencies. Modules of this type are referred to as stacks.

 document: modulemd
 version: 0
 data:
     name: example-stack
     version: 20161201T1301Z.d41d8cd98f00b204e9800998ecf8427e.1.23
     release: 20161201T1301Z.68b329da9893e34099c7d8ad5cb9c940
     summary: An example summary
     description: >
         An example description.
     license:
         module:
             - MIT
     dependencies:
         requires:
             another-module: 0
             one-more: 22

Common Fedora module

A typical Fedora module defines all the mandatory metadata plus some useful references, has build and runtime dependencies and contains one or more packages built from specific commits in dist-git. It relies on Fedora build tools to extract licensing information from the included component and populate the data→license→content list.

 document: modulemd
 version: 0
 data:
     name: common-module
     version: 20161102T1401Z.d41d8cd98f00b204e9800998ecf8427e
     release: 20161102T1401Z.68b329da9893e34099c7d8ad5cb9c940
     summary: An example of a common Fedora module
     description: This module demonstrates what most Fedora modules look like.
     license:
         module: [ MIT ]
     dependencies:
         buildrequires:
             base-runtime: 25
             common-build-tools: 0
         requires:
             base-runtime: 25
     references:
         community: http://www.example.com/common-package
         documentation: http://www.example.com/common-package/docs/5.67/
     profiles:
         default:
             rpms:
                 - common-package
                 - common-plugins
         development:
             rpms:
                 - common-package
                 - common-package-devel
                 - common-plugins
     components:
         rpms:
             api:
                 - common-package
                 - common-package-devel
                 - common-plugins
             packages:
                 common-package:
                     rationale: The key component of this module
                     commit: fd245a0
                 common-plugins:
                     rationale: Extensions for common-package
                     commit: ff09556

Complete module definition

See the modulemd specification.