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