moving additional pages from project wiki to here

2024-12-21 10:48:34 +00:00 · 2024-04-07 21:53:07 -07:00 · 2024-04-07 21:53:07 -07:00 · ce90037808
commit ce90037808
parent c6dc408ccc
7 changed files with 322 additions and 3 deletions
--- a/docs/documentation/.pages
+++ b/docs/documentation/.pages
@ -2,6 +2,7 @@
 nav:
  - ... | index.md
  - Guidelines: guidelines
+  - Debranding and Patching: debranding
  - Composing Releases: compose
  - Empanadas: empanadas.md
  - Peridot: peridot.md
--- a/docs/documentation/debranding/.pages
+++ b/docs/documentation/debranding/.pages
@ -0,0 +1,5 @@
+---
+nav:
+  - ... | index.md
+  - Debranding Information: debrand_info.md
+  - Patching Guide: patching.md
--- a/docs/documentation/debranding/debrand_info.md
+++ b/docs/documentation/debranding/debrand_info.md
@ -0,0 +1,66 @@
+---
+title: Debranding Information
+---
+
+This page goes over the methodology and some packages that require changes to their material for acceptance in Rocky Linux. Usually this means there is some text or images in the package that reference upstream trademarks, and these must be swapped out before we can distribute them.
+
+CentOS had a wiki page at one point where it was documented, but it wasn't always up to date. For example, the package **nginx** did not appear on their list, and still had RHEL branding in the CentOS repos. As a result, this forced us to do a deeper investigation into what needs to be changed or altered.
+
+There are a few ways we've determined some of the changes:
+
+* Packages don't build because ID is not `centos`, `rhel`, or `fedora`
+* Packages have `?centos` tags in the SPEC file to differentiate from Fedora or RHEL
+* Some packages in git.centos.org have an automatic debranding message - This won't be as helpful for 9 and beyond
+* RHEL assets were appearing in the installed package(s)
+
+When we need to make changes, it can possibly be one or more of these things:
+
+* URL's should change from Red Hat to a Rocky page (if applicable)
+* URL's that are being patched to be Red Hat should be removed (systemd in 8 is an example of this)
+* `?centos` is changed to `?rocky`, but this isn't always consistent or sufficient
+* Assets need to be changed
+
+    * Exceptions come when there is a file being requested from the logos package - We generally have symlinks to deal with this
+
+* Some patches must be made to the source code or spec file
+* Packages are built against an "override" release package that uses `ID="rhel"` in `/etc/os-release` to force a build to pose as RHEL (older versions of dotnet and chrony are an example of this)
+
+Current patches (for staging) are [here](https://git.rockylinux.org/staging/patch).
+
+## Packages that need debranding changes:
+
+There is a metadata file that helps track this information for us. It can be located [here](https://git.rockylinux.org/rocky/metadata/-/blob/main/patch.yml) and is separated by section and branch.
+
+In essence, the file goes over these sections:
+
+* `build_patch` -> Packages that may have needed patches to build properly in our environment
+* `dnt` or **D**o **N**ot **T**ouch -> These should not be modified or changed
+* `custom` -> Custom packages not provided by upstream but can be useful in obsoleting packages or providing some functionality
+* `plus` -> Packages that are modified versions of what's in the base or built by normal means but not shipped by Red Hat
+* `previous` -> Packages that may have been patched before for debranding or building - They are left as a reference
+* `provides` -> Common provides for release, logos, and other rocky/system specific packages
+* `override_required` -> Requires an "override" release package to build properly
+* `spec_change_only` -> Requires only spec changes to remove functionality that is RHEL specific
+* `debrand` -> Packages that are changed/patched to either remove Red Hat references, replace them, or add Rocky Linux as a supported distribution
+
+    * Some of these packages will always need to be changed, on a minor or major release schedule.
+    * Some are potentially upstreamed so then they are no longer patched by us (sos is an example)
+    * Some packages may still need modification, even if upstreamed (anaconda is an example)
+
+## Packages that need to become other packages:
+
+There is a metadata file that tracks this for us. It can be located [here](https://git.rockylinux.org/rocky/metadata/-/blob/main/patch.yml). The section in particular is called `provides`.
+
+This is for example, `redhat-logos` or `system-logos` is provided or "becomes" `rocky-logos`.
+
+## Packages that Exist in RHEL, but do not exist in most derivatives
+For sake of complete information, here is a list of packages that are in RHEL, but may not exist in derivatives.  We do not need to worry about these packages:
+
+- insights-client
+- Red_Hat_Enterprise_Linux-Release_Notes-8-*
+- redhat-access-gui
+- redhat-bookmarks
+- rhc
+- rhc-worker-playbook
+- subscription-manager-migration
+- subscription-manager-migration-data
--- a/docs/documentation/debranding/index.md
+++ b/docs/documentation/debranding/index.md
@ -0,0 +1,33 @@
+---
+title: Intro to Debranding with Rocky Linux
+---
+
+## What is Debranding?
+
+Certain packages in the upstream RHEL/CentOS have logos, trademarks, and other specific text, images, or multimedia that other entities (like the Rocky Enterprise Software Foundation) are not allowed to redistribute.
+
+A visible, simple example is the Apache web server (package httpd).  If you've ever installed it and visited the default web server page, you will see a test page specific to your Linux distro, complete with a "powered by" logo and distro-specific information.  While we are allowed to compile and redistribute the Apache web server software, Rocky Linux is NOT allowed to include these trademarked images or distro-specific text.
+
+We must have an automated process that will strip these assets out and replace them with our own branding upon import into our Git.
+
+## How Rocky Debranding Works
+
+Rocky's method for importing packages from the upstream is a tool called **srpmproc**.
+
+Srpmproc's purpose in life is to:
+
+- Clone PACKAGE from our upstream source: git.centos.org/rpms/PACKAGE or gitlab.com/redhat
+- Check if Rocky Linux has any debranding patches available for PACKAGE (under https://git.rockylinux.org/patch/PACKAGE)
+- If patch/PACKAGE exists, then read the configuration and patches from that repository and apply them
+- Commit the results (patched or not) to https://git.rockylinux.org/rpms/PACKAGE
+- Do this for every package until we have a full repository of packages in our Git
+
+## Helping with Debrands
+
+There are 2 tasks involved with debranding: Identifying packages that require debranding and developing patches+configs to debrand the necessary packages.
+
+If you want to help with the latter, please see the [patching guide](patching.md) for examples and a case study. If you find something that you suspect is missing branding, you can also file a [bug report](https://bugs.rockylinux.org) instead.
+
+## Debrand Packages Tracking
+
+A list of packages that need debranding is located in the a metadata file in our git [here](https://git.rockylinux.org/rocky/metadata/-/blob/main/patch.yml). This generally does not track status and is simply a reference on what is debranded, if it's no longer debranded (aka Rocky Linux is upstreamed), and other notes.
--- a/docs/documentation/debranding/patching.md
+++ b/docs/documentation/debranding/patching.md
@ -0,0 +1,210 @@
+---
+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
+```
--- a/docs/index.md
+++ b/docs/index.md
@ -6,11 +6,15 @@ title: Release Engineering (SIG/Core)

 ## About

-The Rocky Linux Release Engineering Team (also known as SIG/Core) dedicates themselves to the development, building, management, production, and release of Rocky Linux. This group combines development and infrastructure in a single cohesive unit of individuals that ultimately make the distribution happen.
+The Rocky Linux Release Engineering Team (also known as SIG/Core) dedicates themselves to the development, building, management, production, and release of Rocky Linux. This group combines development and infrastructure in a single, cohesive unit of individuals that ultimately make the distribution happen.

 The "SIG/Core" reference name is not a strict Special Interest Group (as defined by [the Rocky Linux wiki](https://wiki.rockylinux.org/special_interest_groups/)).

-The primary goal (or "interest") is to ensure Rocky Linux is built and released in a complete and functional manner. The secondary goal is to ensure proper collaboration and development of the Peridot build system.
+The general goals (or "interests") is:
+
+* To ensure Rocky Linux is built and released in a complete and functional manner
+* To ensure proper collaboration and development of the Peridot Build System
+* To ensure all users, developers, and Special Interest Groups are have a solid, stable platform to build upon

 ## Mission

--- a/docs/what_we_do.md
+++ b/docs/what_we_do.md
@ -13,7 +13,7 @@ Some of the things we do in pursuit of our mission goals:
 * Maintenance of the infrastructure used to build and maintain Rocky Linux (such as ansible roles and playbooks)
 * Working with the testing team with images and a platform to test
 * Providing resources for Special Interest Groups
-* Providing assistance and resources for users within the community
+* Providing assistance and resources for users within the community to meet their goals

 "Why the name SIG/Core?"