|
|
| (28 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 and the data section ===
| |
| | |
| Every modulemd file '''MUST''' contain a modulemd document header which consists of the document type tag and the document format version, and a data section holding the module data.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| (...)
| |
| | |
| 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 SRPM 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. See [[Packaging:NamingGuidelines#Package_Versioning]] for details.
| |
| | |
| 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 as its key component should use 2.4.18 for 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 needs 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 might be a reasonable default for most module authors 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 packages and therefore doesn't necessarily have to include this field.
| |
| | |
| Furthermore, the content licenses list should ideally be automatically filled by module build tools rather than the module author.
| |
| | |
| === Module dependencies ===
| |
| | |
| Modules '''MAY''' depend on other modules. These module relationships are listed in the depepdencies section.
| |
| | |
| '''Note:''' This section may change significantly in the future.
| |
| | |
| dependencies:
| |
| buildrequires:
| |
| example-build-dependency: 1.23-1
| |
| requires:
| |
| example-runtime-dependency: 45-1
| |
| | |
| So far modulemd supports two kinds of dependencies:
| |
| | |
| * <code>buildrequires</code> for listing build dependencies of the module, i.e. modules that define the buildroot for building the module's components
| |
| * <code>requires</code> for listing runtime dependencies of the module, i.e. modules that need to be available on the target system for this module to work properly
| |
| | |
| Both these sections contain key-value pairs where keys are the required module names and values the minimum required version in the ''version-release'' format.
| |
| | |
| Either or both of these sections may be omitted.
| |
| | |
| === 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
| |
| | |
| === Module 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/
| |
| | |
| === Module components ===
| |
| | |
| Modules '''MAY''', and most modules do contain a components section defining the module's content.
| |
| | |
| 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 ====
| |
| | |
| Non-RPM content isn't currently supported.
| |
| | |
| == Examples ==
| |
| | |
| === Minimal module ===
| |
| | |
| A minimal module ''example-1.23-1'', containing no packages, having no dependencies whatsoever and defining only the minimal set of required metadata.
| |
| | |
| 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 ===
| |
| | |
| A minimal module, ''example-1.23-1'', containing one RPM package with SRPM name ''foo''. This module doesn't define any dependencies or optional metadata.
| |
| | |
| 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
| |
| | |
| === Minimal module with dependencies only (stack) ===
| |
| | |
| A minimal module, ''example-stack-1.23-1'', containing no packages or any optional metadata besides dependencies. Modules of this type are referred to as ''stacks''.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| name: example-stack
| |
| version: 1.23
| |
| release: 1
| |
| summary: An example summary
| |
| description: >
| |
| An example description.
| |
| license:
| |
| module:
| |
| - MIT
| |
| dependencies:
| |
| requires:
| |
| another-module: 0
| |
| one-more: 22
| |
| | |
| === Common Fedora module ===
| |
| | |
| A typical Fedora module defines all the mandatory metadata plus some useful references, has build and runtime dependencies and contains one or more packages built from specific commits in dist-git. It relies on Fedora build tools to extract licensing information from the included component and populate the <code>data→license→content</code> list.
| |
| | |
| document: modulemd
| |
| version: 0
| |
| data:
| |
| name: common-module
| |
| version: 5.67
| |
| release: 8
| |
| summary: An example of a common Fedora module
| |
| description: This module demonstrates what most Fedora modules look like.
| |
| license:
| |
| module: [ MIT ]
| |
| dependencies:
| |
| buildrequires:
| |
| base-runtime: 25
| |
| common-build-tools: 0
| |
| requires:
| |
| base-runtime: 25
| |
| references:
| |
| community: http://www.example.com/common-package
| |
| documentation: http://www.example.com/common-package/docs/5.67/
| |
| components:
| |
| rpms:
| |
| packages:
| |
| common-package:
| |
| rationale: The key component of this module
| |
| commit: fd245a0
| |
| common-plugins:
| |
| rationale: Extensions for common-package
| |
| commit: ff09556
| |
| | |
| === Complete module definition ===
| |
| | |
| See [https://pagure.io/modulemd/blob/master/f/spec.yaml the modulemd specification].
| |
| | |
| [[Category:Modularization]]
| |
