Updating modules in Fedora

This page will guide you through the process of updating an existing module.

Updating RPM Packages — Pushing new sources.
Updating the Module — Pushing a new version of the modulemd.
Module Build — Module is built as a unit. No individual package builds are done.
Publishing the Module — Submitting a Bodhi update.

Updating RPM Packages

Update your RPM packages the same way you would do traditionally, except submitting individual package builds.

Useful resources:

Updating the Module

Here are the common changes you might want to apply to your modules.

Migrating from modulemd to modulemd-packager format

In the past there was modulemd, version 2, format used for building modules. That format featured stream expansion and dynamic contexts. However, these features were proved impossible to be handled correctly by DNF and thus a new format, modulemd-packager, version 3, was introduced which features a static context.

Modules built from modulemd-packager format are supported since Fedora 34 and RHEL 9.

Changes in the format include:

New document type and version:

    document: modulemd-packager
    version: 3

A module middle-field was removed from the license section:

    license:
        - MIT

A dependencies section:

    dependencies:
        buildrequires:
            platform: ['f34', 'f35']
            perl: ['5.30', '5.32']
        requires:
            platform: ['f34', 'f35']
            perl: ['5.30', '5.32']

was replaced with a configurations section:

    configurations:
        - context: A
          platform: f34
          buildrequires:
              perl: ['5.30']
          requires:
              perl: ['5.30']
        - context: B
          platform: f34
          buildrequires:
              perl: ['5.32']
          requires:
              perl: ['5.32']
        - context: C
          platform: f35
          buildrequires:
              perl: ['5.30']
          requires:
              perl: ['5.30']
        - context: D
          platform: f35
          buildrequires:
              perl: ['5.32']
          requires:
              perl: ['5.32']

The value is a string and its alphabet and length is limited. All the contexts must be unique inside a module stream.

When migrating your modules, you will have to come up with the context value. To preserve a compatibility with the old builds and to preserve the upgrade path, I strongly recommend reusing the old context values. Use Koji https://admin.fedoraproject.org/pkgdb/package/MODULE/, or MBS https://mbs.fedoraproject.org/module-build-service/2/module-builds/?name=MODULE&stream=STREAM&state=5, or dnf module info MODULE:STREAM command (substitute MODULE and STREAM with identifiers of your module) to locate the lastest version of the module, and pick a context matching the desired dependencies as depicted here:

$ dnf -q module info perl-DBI:1.643
Name             : perl-DBI
Stream           : 1.643
Version          : 3520210722203952
Context          : e12b6f3a        ------+
[…]                                      |
Requires         : perl:[5.32]     ----+ |
                   platform:[f35]  --+ | |
                                     | | |
The new YAML file:                   | | |
                                     | | |
data:                                | | |
    configurations:                  | | |
        - context: 'e12b6f3a'   <----|-|-+
          platform: f35         <----+ |
          buildrequires:               |
              perl: ['5.32']           |
          requires:                    |
              perl: ['5.32']    <------+
          buildopts:

The plaform field is a scalar now. However, the stream values of the buildrequires and requires dependencies are a list. Although the specification requires a single value.

A buildopts section was moved from /data to /data/configurations/*/context section. Therefore it’s specific to a context and should be repeated if needed any time:

    configurations:
        - context: A
          platform: f34
          buildrequires:
              perl: ['5.30']
          requires:
              perl: ['5.30']
          buildopts:
              rpms:
                  macros: |
                      %this_is_my_module A
        - context: B
          platform: f34
          buildrequires:
              perl: ['5.32']
          requires:
              perl: ['5.32']
          buildopts:
              rpms:
                  macros: |
                      %this_is_my_module B

And that’s all.

Modules built from this format can be recognized by static_context: true field in their output YAML document.

For a real example of the migration look at any perl* module. For instance, this commit.

Migrating from a dynamic context to a static context

If you do not want to migrate to modulemd-packager format now and you plan to build only for one platform (e.g. only for EPEL 9), but if you still need a static context for better handling in DNF, you should set the context statically by adding into data section:

    static_context: true
    context: CTX (1)

1	Choose a context value as decribed in the previous section about migration to a modulemd-packager format.

Static-context modules are supported since Fedora 34 and RHEL 9.

Static-context modules can be recognized by static_context: true field in their output YAML document.

Updating a module for a new Fedora release

Modules in modulemd-packager format statically define a context for each supported Fedora release:

    configurations:
      - context: CTX1
        platform: f32

When a new Fedora release is branched and Rawhide becomes the next Fedora release, modulemd-packager document is required to be updated to contain a context for the new release. Otherwise, your module won’t be built for the new Rawhide. For instance the above module needs this update:

    configurations:
      - context: CTX1
        platform: f32
      - context: CTX2
        platform: f33

You can use modulemd-add-platform tool from modulemd-tools package to do the change for you:

$ modulemd-add-platform --old f32 --new f33 foo.yaml
$ git diff
diff --git a/foo.yaml b/foo.yaml
index b21b921..38cabe8 100644
--- a/foo.yaml
+++ b/foo.yaml
@@ -4,3 +4,5 @@ data:
     configurations:
       - context: CTX1
         platform: f32
+      - context: f33
+        platform: f33

Rebuilding a module for updated RPM packages

Even when you don’t need to make any changes to the modulemd, you still need to push a new commit to build a new version.

$ fedpkg clone modules/NAME
$ cd NAME
$ fedpkg switch-branch BRANCH
$ git commit --allow-empty -m "update"
$ 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.

Want to help? Learn how to contribute to Fedora Docs ›