Adding new modules to Fedora

This page will guide you through the whole process of adding a new module to Fedora:

  1. RPM Sources — To dist-git/rpms using stream branches.

  2. Module Definition — To dist-git/modules using stream branches.

  3. Module Build — Module is built as a unit. No individual package builds are done.

  4. Publishing the Module — Submitting a Bodhi update.

RPM Sources

For each package in your module, you need to have a Fedora Distribution Git (dist-git) repository under dist-git/rpms with an appropriate stream branch. New packages need to go through a package review.

Repositories and Stream Branches — New packages

The Fedora Package Review Process covers all the steps you need to take, except for stream branches. For that, please continue below to Existing packages.

Repositories and Stream Branches — Existing packages

Requesting new stream branches for existing packages is done with fedpkg, and it doesn’t require a package review.

To create a new branch for a package that shares a name with the module (e.g. "postgresql"), run the following command which will create the package stream branch as well as the module and its stream branch together:

$ fedpkg request-branch --repo=NAME BRANCH --sl SERVICE_LEVEL:YYYY-MM-DD
  • NAME — name of the package and the module

  • BRANCH — name of the stream branch of the package and the module

  • SERVICE_LEVEL:YYYY-MM-DD — expected end of life (e.g. bug_fixes:2020-12-01). The date must end with either 12-01 or 06-01. There are various service levels like bug_fixes, security_fixes, and rawhide. Right now, this is used for locking the branch from pushing new commits there. You can change the date later with a releng ticket. Current dates are stored in Product Definition Center. Other option is to choose a date far in the future so you’re not affected. (Work to fix this is in progress.)

If this package does not share a name with the module (such as for dependencies), then only request the stream branch for this package:

$ fedpkg request-branch --repo=NAME BRANCH --no-auto-module --sl SERVICE_LEVEL:YYYY-MM-DD
  • --no-auto-module — Skip the creation of a module of the same name

Creation of the module and its stream branches separately will be covered later.

Importing the RPM sources into dist-git

The last thing to do is to import the RPM sources into dist-git. Please refer to the New package process for existing contributors for the complete steps.

Module Definition

For your module definition, you also need to have a dist-git repository, this time under dist-git/modules, with an appropriate stream branch. New modules also need to go through a module review in Bugzilla adhering to Fedora Packagining Guidelines for Modules.

Repositories and Stream Branches — New modules

To request a new module repository in dist-git run:

$ fedpkg request-repo --namespace modules NAME BUG
$ fedpkg request-branch --namespace modules --repo NAME BRANCH --sl SERVICE_LEVEL:YYYY-MM-DD
  • NAME — name of the module

  • BUG — bug number with an approved module review in Bugzilla

  • BRANCH — name of the stream branch of the module

  • SERVICE_LEVEL:YYYY-MM-DD — expected end of life. See above for more details. Stream end of lives are available in Product Definition Center.

Repositories and Stream Branches — Existing modules

to request a new stream branch, run:

$ fedpkg request-branch --namespace modules --repo NAME BRANCH --sl SERVICE_LEVEL:YYYY-MM-DD
  • NAME — name of the module

  • BRANCH — name of the stream branch of the module

  • SERVICE_LEVEL:YYYY-MM-DD — expected end of life. See above for more details.

Write and push the modulemd

Writing a modulemd is covered in detail in the Defining Modules in modulemd section.

The name of the modulemd must match the name of the repository. Remember to replace every NAME in the following example.
$ fedpkg clone modules/NAME
$ cd NAME
$ fedpkg switch-branch BRANCH
$ vim NAME.yaml
$ git add NAME.yaml
$ git commit -m "add the initial modulemd"
$ git push
  • NAME — name of the module

  • BRANCH — name of the stream branch of the module

Module Build

NOTE: With Modularity, you no longer build individual packages. Instead, you need to submit a module build.

Submitting module builds is done using fedpkg and is covered in the Building modules section.

Publishing the Module

To make your module available to users, submit as an update to Fedora Bodhi. Make sure you are logged in, and then click on Create / New Update at the top-right corner. Fill out the following fields:

  • Candidate Builds: MODULE_BUILD_ID

  • Update notes: notes for the users

  • Final details: check what applies

One way of getting the MODULE_BUILD_ID is running the same command as in the previous step:

$ fedpkg module-build-info BUILD_ID

and changing the "koji tag" value in the following way:

module-nodejs-10-20180607142235-6c81f848   <- koji tag
       nodejs-10-20180607142235.6c81f848   <- MODULE_BUILD_ID

that is removing the "module-" part at the beginning, and replacing the last "-" with a ".".

Also you can do the same with help of command-line bodhi client:

$ bodhi updates new --type=enhancement --notes="Update to 3.0." --user FAS_USER MODULE_BUILD_ID
================================================================================
     MODULE_BUILD_ID
================================================================================
   Update ID: FEDORA-MODULAR-2019-cee54ead99
Content Type: module
     Release: Fedora 28 Modular
      Status: pending
        Type: enhancement
       Karma: 0
   Autokarma: False  [-3, 3]
     Request: testing
       Notes: Update to 3.0.
   Submitter: FAS_USER
   Submitted: 2019-01-23 11:14:56
    Comments: bodhi - 2019-01-23 11:14:56 (karma 0)
              This update has been submitted for testing by
              FAS_USER.

  https://bodhi.fedoraproject.org/updates/FEDORA-MODULAR-2019-cee54ead99

where FAS_USER is your Fedora Project user name.

Module Stream EOLing/Obsoleting

When a stream should not be used any longer, a user can be instructed to migrate by adding a Module obsoletes document.