Fedora Packaging Guidelines for Modules

Disclaimer

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

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

Every modulemd file MUST contain the modulemd document header which consists of the document type tag and the document format version.

 document: modulemd
 version: 0

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 RPM names.

 name: example

Module version and release

Every module MUST also specify its version and release. The format isn't strictly defined yet but will most likely follow RPM versioning conventions.

 version: 1.23
 release: 1

The version field SHOULD be the same as the main module component version, where applicable. For example a webserver module that contains the httpd-2.4.18 webserver should use 2.4.18 as its version. If this cannot be done, the module maintainer may choose their own versioning scheme.

The release field is incremented when the module is updated in a way that doesn't warrant a version field bump or the module requires to be rebuilt.

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 could be a reasonable default for modules as well.

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