wiki/docs/documentation/debranding/patching.md

title
Rocky Patching Guide

This explains how to debrand/patch a package for the Rocky Linux distribution.

General Instructions

• First, identify the files in the package that need to be changed. They could be text files, image files, or others. You can identify the file(s) by digging into git.centos.org/rpms/PACKAGE/
• Develop replacements for these files, but with Rocky branding placed instead. Diff/patch files may be needed as well for certain types of text, depends on the content being replaced.
• Replacement files go under https://git.rockylinux.org/patch/PACKAGE/ROCKY/_supporting/
• Config file (specifying how to apply the patches) goes in https://git.rockylinux.org/patch/PACKAGE/ROCKY/CFG/*.cfg
  • Note: Use spaces, not tabs.
• When srpmproc goes to import the package to Rocky, it will see the work done in https://git.rockylinux.org/patch/PACKAGE , and apply the stored patches by reading the config file(s) under ROCKY/CFG/*.cfg

The Patch Config Language

Patching uses simple proto3 config files. The general format is:

Action {
    file: "OriginalFile"
    with_file: "ROCKY/_supporting/RockyReplaceFile"
}

A simple example to replace a file:

replace {
    file: "redhatlogo.png"
    with_file: "ROCKY/_supporting/rockylogo.png"
}

The file "redhatlogo.png" would be located in under SOURCES/ in the project's Git repository (and SRPM).

Patch configuration options

• add: Adds a file to the sources using the file or lookaside directive
• delete: Deletes a file from the sources using the file directive
• replace: Replaces a file from the sources using the file and with_file directives
• patch: Performs a patch based on the diff provided in the file directive (generated using git diff)
• spec_change: Allows for spec files to be modified
  • search_and_replace: Performs a search and replace on a given text for the spec file using the any/starts_with/ends_with (true|false), find (string to find), replace (replacement string), and n (integar, -1 for any) directives.
  • file: A file can be added to the spec file using the name directive to define the file name, the type directive (such as patch) and then an add option that is true or false
    • When patch is used, the following options are available:
      • add_to_prep (true|false)
      • n_path: N can be specified to add %patchX -pN lines into %prep assuming the rpm does not use %autosetup
  • append: Appends to a given field, such as Release with a value directive
  • changelog: Modifies the change log using author_name, author_email, and message directives

Patch configuration structure:

.
└── ROCKY
    ├── CFG
    └── _supporting

Case Study: Nginx

(note: all example data here is currently in the staging/ area of Rocky Linux Git. We will update it when the projects are moved to the production area)

Let's go over an example debrand, featuring the Nginx web server package.

The source repository is located here: https://git.centos.org/rpms/nginx

If we browse one of the c8-* branches, we see under SOURCES/ that there is definitely some content that needs to be debranded:

404.html
50x.html
index.html
poweredby.png  (binary file in dist-git, referred to in .nginx.metadata)

These files all refer to Red Hat inc., and must be replaced before they make it to Rocky Linux.

1: Come up with the patches: Each of these files has a Rocky Linux counterpart, and they must be created. Some of this should be done by the Design Team, especially logo work (#Design on chat)

2: Commit patches to the matching patch/PROJECT Git repository : For example, Nginx patches are located here: https://git.rockylinux.org/staging/patch/nginx (staging/ prefix is currently used until our production repos are set up)

3: Develop a matching config file: Our example Nginx has this here: https://git.rockylinux.org/staging/patch/nginx/-/blob/main/ROCKY/CFG/pages.cfg

It looks like this:

replace {
    file: "index.html"
    with_file: "ROCKY/_supporting/index.html"
}

replace {
    file: "404.html"
    with_file: "ROCKY/_supporting/404.html"
}

replace {
    file: "50x.html"
    with_file: "ROCKY/_supporting/50x.html"
}

replace {
    file: "poweredby.png"
    with_file: "ROCKY/_supporting/poweredby.png"
}

4: Test the import: Now, when the upstream is imported, we can check the main Rocky nginx repository and ensure our updates were successful: https://git.rockylinux.org/staging/rpms/nginx/ (again, staging/ group is used only for now)

5: You're Done! Great! Now do the next one... ;-)

More Debrand Config Language

The Nginx example showed just the replace directive, but there are several more available. They are add, patch, and delete.

Here they are, with examples:

# Add a file to the project (file is added to SOURCES/ folder )
add {
    file: "ROCKY/_supporting/add_me.txt"
}

# Apply a .patch file (generated using the Linux "patch" utility)
patch {
    file: "ROCKY/_supporting/002-test-html.patch"
}

# Delete a file from the source project
delete {
    file: "SOURCES/dontneed.txt"
}

And the .patch file example looks like this:

diff --git a/SOURCES/test.html b/SOURCES/test.html
index 8d91ffd..3f76c3b 100644
--- a/SOURCES/test.html
+++ b/SOURCES/test.html
@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 <html>
     <body>
-        <h1>Replace me</h1>
+        <h1>Replace I did!</h1>
     </body>
 </html>

It also supports spec file changes, as it may be necessary. For example, from the anaconda debrand patch repo.

add {
    file: "ROCKY/_supporting/0002-Rocky-disable-cdn-radiobutton.patch"
}

spec_change {
    # Adds a Patch line with the file name as listed above
    file {
        name: "0002-Rocky-disable-cdn-radiobutton.patch"
        type: Patch
        add: true
    }

    # Appends to the end of a field's line, in this case the Release field gets .rocky
    append {
        field: "Release"
        value: ".rocky"
    }

    # Adds to the change log properly
    changelog {
        author_name: "Mustafa Gezen"
        author_email: "mustafa@rockylinux.org"
        message: "Disable CDN and add .rocky to Release"
    }
}

At the end, the spec file should be changed.

Summary:              Graphical system installer
Name:                 anaconda
Version:              33.16.3.26
                      # Our .rocky appears here
Release:              2%{?dist}.rocky

-- snip --

Patch1:               0001-network-do-not-crash-on-infiniband-devices-activated.patch
                      # Look, our patch was added!
                      # Luckily this RPM uses %autosetup, so no %patch lines
Patch2:               0002-Rocky-disable-cdn-radiobutton.patch

-- snip --

# And below the added changelog
%changelog
* Thu Feb 25 2021 Mustafa Gezen <mustafa@rockylinux.org> - 33.16.3.26-2
- Disable CDN and add .rocky to Release

* Thu Oct 22 2020 Radek Vykydal <rvykydal@redhat.com> - 33.16.3.26-2
- network: do not crash on infiniband devices activated in initramfs
  (rvykydal)
  Resolves: rhbz#1890261