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.

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 some packages and therefore doesn't necessarily have to include this field.

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

Module dependencies

TBD

 dependencies:
     buildrequires:
         example-build-dependency: 1.23-1
     requires:
         example-runtime-dependency: 45-1

Extensible module metadata block

TBD

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

Module references

TBD

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

Module components

TBD

 components:

RPM content

TBD

 components:
     rpms:
         dependencies: True
         fulltree: True
         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

Non-RPM content

TBD

Examples

Minimal module definition

TBD

 document: modulemd
 version: 0
 data:
     name: example
     version: 1.23
     release: 1
     summary: An example summary
     description: >
         An example description.
     license:
         module:
             - MIT

Minimal module with RPM content

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