sig_core/wiki
7
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity

Compare commits

base: sig_core:ce90037808f8b3525f4d1d4ed3fe58680aa1768f
Branches Tags
sig_core:main
sig_core:gh-pages
sig_core:update-theme
..
compare: sig_core:4db63afb64a1847990dfb47888e58bc432fa1196
Branches Tags
sig_core:gh-pages
sig_core:main
sig_core:update-theme

No commits in common. "ce90037808f8b3525f4d1d4ed3fe58680aa1768f" and "4db63afb64a1847990dfb47888e58bc432fa1196" have entirely different histories.
ce90037808 ... 4db63afb64

10 changed files with 3 additions and 563 deletions
Show Stats Expand all files Collapse all files

2
docs/documentation/.pages
View File

@ -1,8 +1,6 @@
---
nav:
- ... | index.md
- Guidelines: guidelines
- Debranding and Patching: debranding
- Composing Releases: compose
- Empanadas: empanadas.md
- Peridot: peridot.md

5
docs/documentation/debranding/.pages
View File

@ -1,5 +0,0 @@
---
nav:
- ... | index.md
- Debranding Information: debrand_info.md
- Patching Guide: patching.md

66
docs/documentation/debranding/debrand_info.md
View File

@ -1,66 +0,0 @@
---
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

33
docs/documentation/debranding/index.md
View File

@ -1,33 +0,0 @@
---
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.

210
docs/documentation/debranding/patching.md
View File

@ -1,210 +0,0 @@
---
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
```

4
docs/documentation/guidelines/.pages
View File

@ -1,4 +0,0 @@
---
nav:
- ... | index.md
- ... | rocky_logos_guidelines.md

9
docs/documentation/guidelines/index.md
View File

@ -1,9 +0,0 @@
---
title: Guidelines
---
This section is primarily for documentation and useful information as it
pertains to guidelines for various packages or asset usage.
**Release Engineering has the final "go/no-go" decision on submissions, assets,
images, and the general structure of the release of Rocky Linux.**

227
docs/documentation/guidelines/rocky_logos_guidelines.md
View File

@ -1,227 +0,0 @@
---
title: Rocky Logos Package Guidelines
---
This page goes over the basic guidelines for the rocky-logos package, which produces assets for anaconda, wallpapers, and other assets for the distribution.
**Release Engineering has the final "go/no-go" decision on submissios/assets/images in the package.**
## Rocky Logo Assets
In various parts of the package, the Rocky logo will need to exist in multiple forms:
* Green variant
* White variant
This can be in the form of `PNG`, `JPG`, or `SVG` files.
### anaconda
All anaconda image assets will be in `PNG` form. Backgrounds should be transparent with the exception of `rnotes` if applicable.
### Backgrounds
See [Backgrounds Section](#Backgrounds/Wallpapers)
### fedora
`SVG` format of logo assets as `fedora_logo` (color) and `fedora_logo_darkbackground` (white), and a default as `fedora_logo`.
### firstboot
First boot assets. This is generally the sidebar (like the anaconda installer) and a workstation icon. `PNG` format.
### icons/hicolor
Rocky icons will appear here in different resolutions and must be in `PNG` or `SVG` format:
* 16x16/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 22x22/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 24x24/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 32x32/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 36x36/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 48x48/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 96x96/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* 256x256/apps: `PNG`, `system-logo-icon`, `fedora-logo-icon`
* scalable/apps: `SVG`, `fedora-logo-icon`, `org.fedoraproject.AnacondaInstaller.svg`, `start-here.svg`, `xfce4_xicon1.svg`
* symbolic/apps: `SVG`, `org.fedoraproject.AnacondaInstaller-symbolic`
### ipa
IPA specific assets, usually text. They are generally `PNG` or `JPG`:
* `header-logo.png` - Text
* `login-screen-background.jpg` - No text
* `login-screen-logo.png` - Logo + Text
* `product-name.png` - Text
### pixmaps
`PNG` format, these are usually assets used within GNOME, GDM, and other desktop environments.
### plymouth/charge
Typically unchanged and is for the plymouth loading screen
### svg
`SVG` format of logo assets as `fedora_logo` (color) and `fedora_logo_darkbackground` (white)
`color` file dictates background color if applicable
### testpage
`index.html` for httpd/nginx/etc
## Backgrounds/Wallpapers
### Structure
Wallpapers appear in `PNG` format with a backing `XML` file to list out all available resolutions if applicable, as well as defaults.
A defaults file looks at every other `XML` that is a default background provided by the backgrounds package and default options if applicable.
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
<wallpaper deleted="false">
<name>Rocky Linux 9 Default Background - Placeholder Mesh</name>
<filename>/usr/share/backgrounds/rocky-default-1-mesh.xml</filename>
<options>zoom</options>
<author>Louis Abel</author>
<email>label@rockylinux.org</email>
<license>CC-BY-SA 4.0</license>
</wallpaper>
<wallpaper deleted="false">
<name>Rocky Linux 9 Default Background - Placeholder Target</name>
<filename>/usr/share/backgrounds/rocky-default-1-target.xml</filename>
<options>zoom</options>
<author>Louis Abel</author>
<email>label@rockylinux.org</email>
<license>CC-BY-SA 4.0</license>
</wallpaper>
</wallpapers>
```
The wallpaper itself will list every applicable variant of that background if applicable.
```
<background>
<starttime>
<year>2021</year>
<month>10</month>
<day>29</day>
<hour>19</hour>
<minute>21</minute>
<second>19</second>
</starttime>
<static>
<duration>10000000000.0</duration>
<file>
<!-- Wide 16:9 -->
<size width="1920" height="1080">/usr/share/backgrounds/rocky-default-1-mesh-16-9.png</size>
<!-- Wide 16:10 -->
<size width="1920" height="1200">/usr/share/backgrounds/rocky-default-1-mesh-16-10.png</size>
<!-- Standard 4:3 -->
<size width="2048" height="1536">/usr/share/backgrounds/rocky-default-1-mesh-4-3.png</size>
<!-- Normalish 5:4 -->
<size width="1280" height="1024">/usr/share/backgrounds/rocky-default-1-mesh-5-4.png</size>
</file>
</static>
</background>
```
Day/Night Wallpapers have a similar configuration.
```
<background>
<starttime>
<year>2022</year>
<month>01</month>
<day>01</day>
<hour>8</hour>
<minute>00</minute>
<second>00</second>
</starttime>
<!-- This animation will start at 8 AM. -->
<!-- We start with day at 8 AM. It will remain up for 10 hours. -->
<static>
<duration>36000.0</duration>
<file>/usr/share/backgrounds/rocky-default-1-mesh-day.png</file>
</static>
<!-- Day ended and starts to transition to night at 6 PM. The transition lasts for 2 hours, ending at 8 PM. -->
<transition type="overlay">
<duration>7200.0</duration>
<from>/usr/share/backgrounds/rocky-default-1-mesh-day.png</from>
<to>/usr/share/backgrounds/rocky-default-1-mesh-night.png</to>
</transition>
<!-- It's 8 PM, we're showing the night till 6 AM. -->
<static>
<duration>36000.0</duration>
<file>/usr/share/backgrounds/rocky-default-1-mesh-night.png</file>
</static>
<!-- It's 6 AM, and we're starting to transition to day. Transition completes at 8 AM. -->
<transition type="overlay">
<duration>7200.0</duration>
<from>/usr/share/backgrounds/rocky-default-1-mesh-night.png</from>
<to>/usr/share/backgrounds/rocky-default-1-mesh-day.png</to>
</transition>
</background>
```
### Guidelines
This section goes over the general guidelines for the main backgrounds included in the distribution.
**Note**: It is **highly recommended and encouraged** that a submission should be the highest resolution as noted below. See the [note](#minimum-resolutions) on minimum resolutions.
* **General Theme**: Each Rocky release has a codename, and thus is the general theme. Examples.
* Rocky 8: `Green Obsidian` - Submissions only to extras
* Rocky 9: `Blue Onyx` - This should be generally a blue theme/color scheme. Submissions only to extras.
* Rocky 10: `Red Quartz` - This should be generally a red-like theme/color scheme
* **Required Resolution(s) for Normal Submissions**:
* Resolution must **not** exceed nor fall below: 4092x3072
* **Allowed**:
* Anything related to nature, mountains, rocks, and the like (generally fitting into the "rocky" idea)
* Anything related to the codename (eg. Blue Onyx)
* Anything minimalist/abstract is allowed
* References to the release number (like 9, and so on) are allowed
* Complementary colors should be allowed in the image within reason
* Contrasting colors should be allowed in the image within reason
* Photography + Manipulation should be allowed within reasonG
* **Highly Encouraged**: [Day](https://github.com/fedoradesign/backgrounds/raw/f34-backgrounds/default/f34-01-day.png) and [Night](https://github.com/fedoradesign/backgrounds/raw/f34-backgrounds/default/f34-02-night.png) versions of wallpapers
* **Discouraged**:
* Avoid using the Rocky logo, unless it fits with an abstract/minimalist idea for the background
* Plain backdrops with the rocky logo are *not* permitted
#### Minimum Resolutions
For general submissions, we require the highest resolution to make things simpler, that way the user should be able to use a wallpaper without having to choose "the right one" for their monitor size. However, for the case case of extra backgrounds, this requirement is more relaxed. If a submitter wishes not to use the highest resolution but opts to make multiple resolutions instead, they should follow the below list:
* **Minimum Required Resolutions**:
* 16:9 (1920x1080)
* 16:10 (1920x1200)
* 5:4 (2048x1536)
* 4:3 (1280x1024)
* **Additional (encouraged) allowed resolutions**:
* 3440x1440
* 2560x1600
* 2560x1440
* 2560x1080
* 1800x1440
* Portrait mode versions of the above are optional
The placeholders in [this commit](https://github.com/rocky-linux/rocky-logos/tree/962a836f70a131faa541a4f8f73a4a3fddfc3dbf/backgrounds) shows an example of using the minimum resolutions.
### Extras Package
If a wallpaper does not make it to the main package (whether it doesn't meet guidelines or is simply just Rocky inspired), they should be able to be submitted for addition into the `rocky-backgrounds-extras` package.

8
docs/index.md
View File

@ -6,15 +6,11 @@ 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 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
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.
## Mission

2
docs/what_we_do.md
View File

@ -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 to meet their goals
* Providing assistance and resources for users within the community
"Why the name SIG/Core?"