Fedora Packaging Guidelines for Modules

These guidelines specify restrictions and guidance for defining-modules.adoc.

Short Overview

  • Packager MUST specify summary

  • Packager MUST specify description

  • Packager MUST specify license/module license(s) based on allowed licenses in Fedora

  • Packager MUST specify dependencies

  • Packager MUST specify components

  • Packager SHOULD specify profiles

  • Packager SHOULD specify api

  • Packager MAY specify data in key-value format in xmd

  • Packager MAY specify references

  • Packager MAY specify filter

  • Packager MAY specify buildopts

  • Packager MUST NOT specify name, name is taken from name of dist-git repository

  • Packager MUST NOT specify stream, stream is taken from branch of dist-git repository

  • Packager MUST NOT specify version, it is automatically generated by buildsystem

  • Packager MUST NOT specify arch, it is automatically filled in by buildsystem

  • Packager MUST NOT specify servicelevels, they are automatically filled in by buildsystem from PDC

  • Packager MUST NOT specify license/content license(s), they are picked up from components which are built

  • Packager MUST NOT specify artifacts

Long Overview

Document header and the data block

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

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

The version is an integer and denotes the version of the metadata format the rest of the document is written in. Packagers SHOULD use latest available version of specification.

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.

Licensing

Every module MUST contain a license block 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.

Dependencies

Modules MAY depend on other modules. These module relationships are listed in the dependencies block. However, none of modules are buildable without platform module hence packagers are required to specify it.

Packagers SHOULD be using stream name expansion to make their modules compatible with other existing modules. The following example builds and runs the module on any platform:

dependencies:
  - buildrequires:
      platform: []
    requires:
      platform: []

Note the stream name expansion is only supported by the second version of the format. Unlike in the first version, the dependencies block is a list of dictionaries.

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

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/

Profiles

The module author MAY define lists of packages that would be installed 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 few special-purpose profile names defined, see specification for details.

If the module includes one or more profile definition, managing-defaults.adoc SHOULD also be defined.

In the case of RPM content, the profile package lists reference binary RPM package names.

API

Module API are components, symbols, files or abstract features the module explicitly declares to be its supported interface. Everything else is considered an internal detail and shouldn’t be relied on by any other module.

Every module SHOULD define its public API.

Filters

Module filters define lists of components or other content that should not be part of the resulting, composed module deliverable. They can be used to only ship a limited subset of generated RPM packages, for instance.

filter:
    rpms:
        - mypackage-plugins

Currently the only supported type of filter are binary RPM packages.