|
|
| (29 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| {{DISPLAYTITLE:Fedora Packaging Guidelines for Modules}}
| | #REDIRECT [[Module:Guidelines]] |
| <div style="float: right;" class="toclimit-2">__TOC__</div>
| |
| | |
| == 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 [https://pagure.io/modulemd 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
| |
| | |
| === Complete module definition ===
| |
| | |
| [[Category:Modularization]]
| |
