| This page is a placeholder. You can make this page more useful by submitting a pull-request to https://pagure.io/fedora-docs/modularity/ |
Traditionaly, each package would have multiple branches, one for every release. Such scheme is very straighforward, but limits us in two ways:
Only one version of a package can be built for each release
Even when there is the same version for multiple releases, packagers need to maintain multiple branches
Modularity introduces some new features to the build pipeline:
Instead of branching per release, packages are branched per major version. This reduces the source duplication and the number of branches packagers need to maintain.
An ability to build one source branch for multiple releases.
Modules are the mechanism of delivering additional versions of packages to Fedora. They have independent lifecycles and are usualy built for all supported Fedora releases.
Thanks to these features, it becomes possible to build multiple versions of packages for all releases while maintaining lower number of branches.
If you wish to package an alternative version of something, or if you wish to maintain your packages on an independent lifecycle to the Fedora release, modules are the way to go.
In general, modules represent an application, a language stack, a logical group of tools, or even a single package. An example could be httpd, PostgreSQL, developer tools, etc.
Modules have one or more streams. Streams are very similar to a major version of an application, i.e. Nodejs 6 vs. Nodejs 8, but also "latest" or "devel". Streams have independent lifecycles.
In technical terms, modules can replace or provide additional packages to the traditional Fedora releases.
When making a new module, think of the major three things:
a name that would represent it well i.e. nodejs, postgresql, django.
a stream name that would best describe its lifecycle and compatibility goal i.e. a major version, latest, devel, etc. We expect that using a major version will be the most common stream name.
a list of packages the module will provide.
There are other aspects of modules, but these three are the most important ones.
Modules are defined using a modulemd file. A minimal example:
| The following example is modulemd version 1 that doesn’t support stream expansion. We are introducing a new version very soon. |
modulemd.yaml
document: modulemd
version: 1
data:
summary: An example module (1)
description: >-
A module for the demonstration (2)
of the metadata format.
license:
module:
- MIT (3)
dependencies: (4)
buildrequires:
platform: f27
requires:
platform: f27
references: (5)
community: http://www.example.com/
documentation: http://www.example.com/
tracker: http://www.example.com/
profiles: (6)
default:
rpms:
- foo
- foo-extras
minimal:
description: Minimal profile.
rpms:
- foo
api: (7)
rpms:
- foo
components: (8)
rpms:
foo: (9)
rationale: Our main package. (10)
ref: 2.4 (11)
bar:
rationale: Some another package.
ref: latest| 1 | A short summary describing the module. |
| 2 | A longer summary describing the module. |
| 3 | Licence of this modulemd file. |
| 4 | Other modules and their streams that are used as runtime and build dependencies. "platform" is a reserved word for the Fedora releases. The stream names follow the usual short names for the releases i.e. "f26", "f27", "epel7", etc. In this version of modulemd (v1) there is no support for stream expansion. That means that only one release can be selected. However, in the upcoming version of modulemd (v2) there will be an option to list multiple ones. |
| 5 | Various references to the upstream. |
| 6 | Installation profiles that will help users to install the module. Keep in mind that not all the packages from the module need to be installed. |
| 7 | The module’s public RPM-level API. A list of binary RPM names that are considered to be the main and stable feature of the module |
| 8 | List of packages that are part of this module. |
| 9 | Name of a package. |
| 10 | A rationale why the package has been included. This is only for humans. |
| 11 | A dist-git branch of the package. |
explain module.yaml, what it should be named, what the branch should be called, where to find the spec, some example
