From 81c3e32e02d9ea8ac3959923ed03389d86be8952 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 20 Aug 2026 09:29:37 +0200 Subject: [PATCH] docs: rework release documentation Signed-off-by: Eike Waldt On-behalf-of: SAP --- MAINTAINER.md | 265 ------------------------------- PATCHING.MD | 91 ----------- docs/explanation/packaging.md | 46 +++++- docs/how-to/backporting.md | 77 ++++++--- docs/how-to/github-actions.md | 36 +++++ docs/how-to/package-releases.md | 272 +++++++------------------------- 6 files changed, 187 insertions(+), 600 deletions(-) delete mode 100644 MAINTAINER.md delete mode 100644 PATCHING.MD diff --git a/MAINTAINER.md b/MAINTAINER.md deleted file mode 100644 index 6cef2c0..0000000 --- a/MAINTAINER.md +++ /dev/null @@ -1,265 +0,0 @@ -# Maintainer Guide - -This guide is written for Garden Linux maintainers, explaining the steps required for creating a package for Garden Linux. -Along the series of steps, we will introduce rules in the correct context, which are outlined in the table presented in the [Overview of Rules](#overview-of-rules). - -> [!NOTE] -> The overall Garden Linux release process is described in a Garden Linux Maintainer internal document [here](https://github.com/gardenlinux/process/blob/main/release.md). - - -## Overview of Rules -| Rule Number | Description | -|-------------|-------------------------------------------------------| -| [Rule 1](#rule-1-package-git-repositories-must-be-named-accordingly) | Package git repositories must be named accordingly | -| [Rule 2](#rule-2-git-branches-of-package-repositories-must-be-named-accordingly) | Git branches of package repositories must be named accordingly | -| [Rule 3](#rule-3-one-shot-build-dependency-repositories-must-start-with-bp-package) | One-shot build dependency repositories must start with bp-package | -| [Rule 4](#rule-4-for-existing-debian-packages-get-debian-folder-from-garden-linux-snapshot-apt-repo) | For existing debian packages, get debian folder from Garden Linux snapshot apt repo | -| [Rule 5](#rule-5-create-debian-folder-in-package-repo-only-if-debian-package-does-not-exist) | Create `debian/` folder in package repo only if Debian package does not exist | -| [Rule 6](#rule-6-get-upstream-source-from-upstream-git) | Get upstream source from upstream git | -| [Rule 7](#rule-7-patching-the-patches) | Patching the patches | -| [Rule 8](#rule-8-append-to-debian-patches) | Append to debian patches | - - -# Use Cases - - -| Use Case | Description | -|-------------------------------------|------------------------------------------------| -| [Use Case 1](#use-case-1-build-package-with-garden-linux-pipelines) | Build package with Garden Linux pipelines | -| [Use Case 2](#use-case-2-build-backport-package-with-garden-linux-pipelines) | Build Backport package with Garden Linux pipelines | -| [Use Case 3](#use-case-3-create-build-dependency-package-with-garden-linux-pipelines) | Create build dependency package with Garden Linux pipelines | -| [Use Case 4](#use-case-4-local-builds) | Local builds | - -## Use Case 1: Build package with Garden Linux pipelines -How to do a regular package build is described [here](https://github.com/gardenlinux/package-build/blob/main/README.md#github-action-build). - -#### Rule 1: Package git repositories must be named accordingly -``` -package- -``` -- must start with `package-` -- `` must be the name of the source package as it is defined in debian - - exception: if package does not exist in debian - -## Use Case 2: Build Backport package with Garden Linux pipelines -How to do a backport package build is described [here](https://github.com/gardenlinux/package-build/blob/main/README.md#patch-releases--backporting). - -#### Rule 2: Git branches of package repositories must be named accordingly - -Branch types: -- `main`: builds against latest Garden Linux environment -- `rel-`: builds against `` version of Garden Linux. -- `fix/*`, `feat/*`, `other/*`: are allowed to indicate that the branch is used temporarily for work in progress - -## Use Case 3: Create build dependency package with Garden Linux pipelines - -In the case when a package `ABC` requires a build dependency `XYZ` in a certain version or with a certain patch applied, we use the bp-package repositories, -which are one-shot build dependency packages. - -Those packages are NOT included in the package-releases file of gardenlinux/repo, but they are included in the package build of `ABC` with the [build_dep](https://github.com/gardenlinux/package-build/blob/290959d6fc5ba4f8c378ef931f66e7bed2b134b4/.github/workflows/build.yml#L10) argument like this: - -``` -on: - push: - workflow_dispatch: - schedule: - - cron: '0 0 * * *' -jobs: - build: - uses: gardenlinux/package-build/.github/workflows/build.yml@main - with: - release: ${{ github.ref == 'refs/heads/main' }} - build_dep: gardenlinux/package-XYZ 0.0.1-0gl0+bpwhatever -``` - -#### Rule 3: One-shot build dependency repositories must start with bp-package -Package repositories only required as a dependency for a backported package must start with bp-package-*. - -## Use Case 4: Local builds -Building packages locally is explained [here](https://github.com/gardenlinux/package-build/blob/main/README.md#local-package-build), no rules apply. - - -# Package build process - -The package build process is described in further detail in this chapter in addition to the short guide in the [README.md](https://github.com/gardenlinux/package-build/blob/main/README.md). - - -Overview of steps to make a package for Garden Linux: -``` -1. prepare the package source -2. make source package -3. make binary package(s) -4. test binary package(s) -5. handover to repo build -``` - -We will walk through each step in detail below. - - - -## Prepare the package Source - -The source to create a package consists of three parts. -1. The **upstream source code** -2. The **debian/ folder** -3. **Garden Linux patches** - -It is the task of the Garden Linux package maintainer to define in the `prepare_source` script where to get upstream source, debian folder and what patches to add on top. -In the following we will go through each of the three mentioned parts, and how to assemble them. - -Since prepare_source is invoked directly in the package-build pipeline as step in [gardenlinux/package-build:bin/source](https://github.com/gardenlinux/package-build/blob/main/bin/source), we have access to multple helper functions inside the prepare_source script. Those helper scripts are introduced in context below. - -### Get debian/ folder - -The debian folder contains patches, configurations and rules to make and install the software. For more details about the required content of that debian folder, read [debian documentation](https://www.debian.org/doc/manuals/maint-guide/dreq.en.html). - -To create a Garden Linux package, we also need a **debian/ folder** including all the required files. -In the following we define how we **SHOULD** get the debian folder, depending on the case: - - -| Case | Recommended way to get debian folder | Debian Security Tracking? | Example | -| ---- | ----------- | -------------------------------------------------- | ------- | -| Package not available in debian at all | manually maintain the **debian/ folder**. | not possible | metalbond | -| Package available in debian testing | get debian folder from out apt snapshot | yes | systemd | -| Package not available in debian testing, but in salsa | get debian folder from salsa | yes | our selected linux LTS | - - -#### Rule 4: Recommended way of getting debian folder is from snapshot apt-src repo -Get debian/ Folder from those snapshots, as described below - -The helper script [apt_src](https://github.com/gardenlinux/package-build/blob/621c4c8f530a93884f7b9a4dfc348a50a2d19aa5/bin/source#L31C1-L31C8) must be used in prepare_source like this: -``` -apt_src --ignore_orig -``` -> [!NOTE] -> All Debian packages from testing are mirrored daily in a Garden Linux snapshot apt repository, if a source package is missing in a snapshot, salsa may be used to get a debian/ folder. - -#### Rule 5: For packages not existing in debian at all, create `debian/` folder in package- git repo - -If there does **NOT** exist a debian package, we must define the **debian/ folder** ourself and check it in our `package-` repository. - - -### Get upstream source - -We **MUST** watch upstream git repository automatically, and automatically trigger pipelines to build and test new upstream versions without waiting for a debian maintainer to upgrade salsa. -For that, we use a scan tooling based on debian's uscan. Rules for this tool are defined per package in `debian/watch`, and include what target upstream repo to watch, and what to watch including what semversion changes should be pulled (e.g. only patchlevel). - -> [!WARNING] -> Guide on how to define these `debian/watch` rules is to be done! - -#### Rule 6: Get upstream source from upstream git -To enable automatic upstream version tracking, get source from upstream git repository. -This means do NOT use apt source packages, do NOT use patches to update to a version. - -``` -version_orig=1234 -git_src --branch -``` - -### Garden Linux Patches - -Garden Linux Patches are applied on top of debian patches. - -> [!WARNING] -> see patching guide --- insert link here --- - -#### Rule 7: Patching debian patches -We consider the debian/patches folder as source, and changes to debian/patches are done and tracked via patches. -Patches for debian folder are put in folder `fixes_debian` and applied with helper function `apply_patches`. - -
- brief guide on how to create a Patch with package-build tools - -``` -package-build/build --leave-artifacts --source-only package-XYZ -package-build/build --edit package-XYZ -mkdir -p ../fixes_debian -cd run_ -pushd b -# ... Do your changes, recommending quilt -popd -# create your patch -diff -Naur a/debian b/debian > ../../fixes_debian/your-changes-and-fixes.patch -# append your patch to series file -echo "your-changes-and-fixes" >> ../../fixes_debian/series -``` -
- - - -#### Rule 8: Append to `debian/patches` -Patches for upstream source are put in folder `upstream_patches` and applied with helper function `import_upstream_patches#` -This helper function copies the patches to debian/patches and appends them to debian/patches/series - -> [!NOTE] -> This allows us to conviniently import and maintain patches from upstream (e.g. cherry-pick an upstream commit on a different branch that fixes a CVE). - -# Make source package -A source package contains all the necessary files to build the binaries, and will be used as input by the next step [Make binary package](##Make-binary-package). - -A definition of a debian source package can be found [here](https://wiki.debian.org/Packaging/SourcePackage). - - -The central gardenlinux/package-build repo contains reusable actions, that are used to automatically perform this step. For reference, see that reusable action [here](https://github.com/gardenlinux/package-build/blob/621c4c8f530a93884f7b9a4dfc348a50a2d19aa5/.github/workflows/build.yml#L29) - - -# Make binary package - -Input for this stage is a debian source package created by the previous stage. -The central gardenlinux/package-build repo contains reusable actions, that are used to automatically perform this step, as well. - -You can add a `prepare_binary` script to the package-XYZ repo to perform additional preparations before the binary build step is executed. -You could for example reconfigure debian build profiles, install build dependencies or add some logging flags for debugging. - -# Test binary package - - -Tests are currently disabled by default via the `nocheck` debian build profile. - -From [Debian wiki](https://wiki.debian.org/BuildProfileSpec#The_DEB_BUILD_PROFILES_environment_variable) -> nocheck: No test suite should be run, and build dependencies used only for that purpose should be ignored. Builds that set this profile must also add nocheck to DEB_BUILD_OPTIONS - - -# Handover to repo build -The gardenlinux/repo is responsible for pulling all required packages and create the apt repositories. -Packages are either collected from a debian mirror, or from the respective GitHub release page in case we build the package with Garden Linux package-build pipelines. - -## Daily release -A daily scheduled gardenlinux/repo action collects all latest releases and creates a new apt repository based on latest packages. - -1. Get list of `gardenlinux/package-*` repositories -2. Download each package/version from GitHub Releases of respective package-* git repo. - - -## Patch release -Packages for patch releases are also uploaded to the GitHub Release page, but must be manually selected in the gardenlinux/repo to be included for a certain patch release apt repository. - -## Disable a package-XYZ repository (NULL release handling) -If a package-XYZ build must be excluded in next nightly apt repositories, a so called "NULL release" must be published for package-XYZ. - -> [!IMPORTANT] -> If you want to remove/archive a package from Garden Linux by creating a null release, follow this [guide](https://github.com/gardenlinux/repo?tab=readme-ov-file#remove-garden-linux-packages-from-the-repo). - -### What happens under the hood -The [fetch_releases](https://github.com/gardenlinux/repo/blob/main/fetch_releases) script runs as part of the github actions of gardenlinux/repo. -`fetch_releases` goes through all repositories in gardenlinux org, and gets the latest release tag. - -The [download_pkgs](https://github.com/gardenlinux/repo/blob/ce6205aabdabd8e578c963bf230aee5e91beeb5e/download_pkgs#L27) downloads all latest release files from all the package-* GitHub Releases. -If the latest release of a given package-* contains `null` file, it is ignored and not included in the apt repository. - -### How to do a null release - -``` -git checkout --detach -git commit --allow-empty -m "ignore package for repo import" -git tag null -git push origin null -echo "" > null -gh release create null ./null --title "Null release" --notes "null" -``` - - -If package-XYZ already has a null release but is not set as latest, you can set it manually as latest again to achieve the same result of gardenlinux/repo ignoring package-XYZ for next nightly apt repo. - - - diff --git a/PATCHING.MD b/PATCHING.MD deleted file mode 100644 index b376124..0000000 --- a/PATCHING.MD +++ /dev/null @@ -1,91 +0,0 @@ -# Create or fix Patches - -In the following we will go through one way of creating a patch for a gardenlinux package. -We will use the repository package-linux and the resulting gardenlinux package "linux" as an example. - -#### 1. Prepare your local sources - -First, we need the sources of the package-linux with all patches applied exactly as the GitHub package-build pipeline would do. -Later on, when we have the sources, we can fix, remove, add patches to the sources easily. - - -``` -./package-build/build --leave-artifacts --source-only package-linux -``` -This step has called the [package-build/bin/source](https://github.com/gardenlinux/package-build/blob/main/bin/source) script inside a container, and placed the sources inside the local folder `package-linux/output/run-/a`, and another copy `package-linux/output/run-/b` right next to it. Even if the source script fails to apply a certain patch, you will have the source folders exactly in the state where the source build left bailed out. - - -> [!Warning] -> If you run this on arm64, then you need to also pass `--arch arm64` for the source build. Cross-build for generating sources is not required and might cause issues. - -> [!Note] -> If the package-build/bin/source has failed, the sources are kept and are in the state where the package-build/bin/sources exited. - -#### 2. Spawn a temporary linux container to use quilt - -Quilt is a versatile tool for working with patches. You can use it to fix, add or remove patches. -Patches inherited from debian (the patches inside the debian/patches folder that we pull) are in allmost all cases maintained with quilt. - -If we want to fix a patch from debian, then we need to make sure to use the same patch format as debian. Quilt can be [configured accordingly](https://wiki.debian.org/UsingQuilt#Using_quilt_with_Debian_source_packages). - -The following command spawns a container with quilt already configured correctly. - - -``` -./package-build/build --edit package-linux -``` - -This starts a debian container with the output folder generated from the previous step mounted. - -Preparations are defined in [package-build/bin/patchenv-init](https://github.com/gardenlinux/package-build/blob/main/bin/patchenv-init), -you can review those and use your local machine instead. - -#### 3. Make your changes inside folder b - -Keep folder `a` as is, and do your work in folder `b`. -This will allow us later to produce a patch. - -At this stage, knowing how to use [quilt](https://en.wikipedia.org/wiki/Quilt_(software)) is very helpful. - -##### Quilt Quick Reference - -`quilt push` apply a single patch - -`quilt push -a` apply all patches - -`quilt push -f` force apply patches - -`quilt refresh` update patch files after manually editing source - -##### External Quilt References and Tutorials - -- The Debian guide [references this tutorial](http://www.shakthimaan.com/downloads/glv/quilt-tutorial/quilt-doc.pdf), licensed under the GNU Free Documentation License, and may be a good starting point for you. -- [wiki.debian.org: Using Quilt - Refresh a patch that failed to apply](https://wiki.debian.org/UsingQuilt#Refresh_a_patch_that_failed_to_apply) - -#### 4. Create the patch - -The diff between folder a and your edited folder b is now the patch. We just need to create it in an acceptable format: - -``` -diff -Naur a/ b/ > name-of-your-patch.patch -``` - -> [!Tip] -> If you already know what file has changed, e.g. because you fix a debian/patch/file, then you can instead use -> ``` -> diff -Naur a/path/to/file b/path/to/file > name-of-your-patch.patch -> ``` - -#### 5. Append the patch to the patches folder - -Depending on the package you are working on, there may or may not already exist an appropriate patches folder where you can add the `name-of-your-patch.patch` to. - -If it does not exist yet, you need to create a folder (e.g. called `fixes_debian`) and then adapt the prepare_source script to apply patches by adding for example this line -``` -apply_patches fixes_debian -``` - -apply_patches is a bash function sourced from [package-build/bin/source](https://github.com/gardenlinux/package-build/blob/main/bin/source) that applies all patches as defined by the series file. -See example [package-linux](https://github.com/gardenlinux/package-linux/blob/18baefb947b6fb3a4abaa9c58b6a42be3117e6dd/prepare_source#L30C1-L30C27) - - diff --git a/docs/explanation/packaging.md b/docs/explanation/packaging.md index 30e32e6..e1b20ce 100644 --- a/docs/explanation/packaging.md +++ b/docs/explanation/packaging.md @@ -45,7 +45,7 @@ The [`package-build`](https://github.com/gardenlinux/package-build) repository p ## Source Package Repositories (`package-*`) -Each custom-built package has its own GitHub repository following the naming convention `package-{package_name}` (e.g., `package-containerd`, `package-openssh`). These repositories contain: +Each custom-built package has its own GitHub repository following the naming convention `package-{package_name}` (for example, `package-containerd`, `package-openssh`). These repositories contain: - The source code or references to upstream sources - Build scripts and configuration @@ -71,21 +71,51 @@ These repositories are built using the tools in the `package-build` repository. ## Understanding package versions -Garden Linux packages typically follow versioning like: +Garden Linux packages follow versioning like: ``` --~gardenlinux +-gl[+bp] ``` -For example: `1.2.3-1~gardenlinux0` +For example: `8.21.0-2gl0+bp2150` Where: -- `1.2.3` is the upstream version -- `-1` is the Debian revision -- `~gardenlinux0` indicates this is the first Garden Linux rebuild +- `8.21.0` is the upstream version +- `-2` is the Debian revision +- `gl0` is the Garden Linux build increment, starting at `gl0` (`gardenlinux0` for older releases) and incremented for each new GL rebuild of the same upstream+Debian version (for example, `gl1`, `gl2`) +- `+bp2150` identifies the Garden Linux major release this build targets (2150.x in this example) -When creating patch releases or backports, the suffix is incremented (e.g., `~gardenlinux1`, `~gardenlinux2`) or modified for specific use cases (like `~bp1443` for backports). +### Version suffix and branch model + +Each `package-*` repository uses a multi-branch model: + +| Branch | Purpose | Tag suffix | +|---|---|---| +| `main` | Nightly / development track. Feeds daily GL snapshot releases. | None — tags like `8.21.0-2gl0` | +| `rel-` | Maintenance branch for a specific supported GL major release `N`. | `+bp` — tags like `8.21.0-2gl0+bp2150` | + +The `version_suffix` variable in the `prepare_source` script controls which suffix the build system appends: + +- On `main`, the CI auto-appends `gl0` when `release: true` is set in the workflow input. +- On `rel-` branches, `version_suffix` is set explicitly in `prepare_source`, for example `version_suffix=gl0+bp2150`. + +The build system reads `version_suffix` to form the package version and the git tag. When the same upstream version is rebuilt (for example, to fix a build dependency), the increment is bumped: `gl0` → `gl1`. + +### Examples using `package-curl` + +| Tag | Branch | Meaning | +|---|---|---| +| `8.21.0-2gl0` | `main` | First GL build of curl `8.21.0-2`; nightly | +| `8.21.0-2gl0+bp1877` | `rel-1877` | Backport of curl `8.21.0-2` for GL 1877.x | +| `8.21.0-2gl0+bp2150` | `rel-2150` | Backport of curl `8.21.0-2` for GL 2150.x | +| `8.20.0-2gl1+bp2150` | `rel-2150` | Second Backport of curl `8.20.0-2` for GL 2150.x | + +::: note Version encoding + +The `+` character in git tags corresponds to `~` (tilde) in the Debian package version string stored inside `prepare_source` (for example, `version_suffix=gl0~bp2150`). The tilde sorts lower in Debian version comparison, which ensures the backport version sorts below the corresponding nightly version in APT. The build system translates `~` to `+` when creating the git tag. + +::: ## Related topics diff --git a/docs/how-to/backporting.md b/docs/how-to/backporting.md index 6250e9c..00c210a 100644 --- a/docs/how-to/backporting.md +++ b/docs/how-to/backporting.md @@ -30,33 +30,68 @@ This guide covers how to create patch releases and backport packages in Garden L For foundational knowledge on package creation and repository structure, see the [Packaging Rules](/reference/packaging-rules.md) reference. +## Branch and tag conventions + +Each `package-*` repository uses a [multi-branch model and version suffixes](/explanation/packaging#Version-suffix-and-branch-model) to separate nightly development from stable release maintenance. + +### Tags + +Tags on `package-` reposotories correspond with the [Package Versions](/explanation/packaging#understanding-package-versions) + +### Setting the version suffix + +The `version_suffix` variable in `prepare_source` controls the tag: + +- On `main`: no `version_suffix` line. The CI auto-appends `gl0` when `release: true` is set in the workflow call. +- On `rel-`: set `version_suffix` explicitly in `prepare_source` (typically at the end of the file), for example: + + ```bash + # in prepare_source on branch rel-2150 + version_suffix=gl0+bp2150 + ``` + +:::info +Inside `prepare_source`, you may also write `version_suffix=gl0~bp2150` (with a tilde). The tilde ensures the backport version sorts below the corresponding nightly version in APT. The build system translates `~` to `+` when creating the git tag. +::: + ## Creating patch releases -When running the GitHub Actions job with `release: true`, it automatically creates a new release with version suffix `gl0` (or `gardenlinux0` in older packages). To create a patch release for this version: +A patch release delivers an updated package version to an already-shipped Garden Linux release. You work on the `rel-` branch that corresponds to the target release. + +The example below uses `package-curl` targeting Garden Linux 2150.x. The starting tag is `8.21.0-2gl0+bp2150` and the goal is to produce patch tag `8.21.0-2gl1+bp2150`. ### 1. Check out the release tag ```bash +git clone https://github.com/gardenlinux/package-curl +cd package-curl git fetch --tags -git checkout gl0 -git branch -git checkout +git checkout 8.21.0-2gl0+bp2150 +git switch -c patch/8.21.0-2gl1+bp2150 ``` +This creates a local working branch from the release tag so you can make and review changes before pushing to the permanent `rel-2150` branch. + ### 2. Apply modifications -Make the necessary changes or backport patches from the main branch. For detailed patching guidance, see the [Patching](/how-to/packaging/patching.md) guide. +Make the necessary changes or backport patches from `main`. For detailed patching guidance, see the [Patching](/how-to/packaging/patching.md) guide. ### 3. Increment the version suffix -The GitHub Actions job that created the `gl0` tag automatically added a `version_suffix=gl0` line to the `prepare_source` script. Simply increment this suffix. +In `prepare_source`, increment the `gl` counter in `version_suffix`: -In certain scenarios where you want to backport to an older Garden Linux version, you will also need to update the `.container` file and use the appropriate container image. +```bash +# before +version_suffix=gl0+bp2150 -:::tip -You can use the [`bin/find-build-container-for`](https://github.com/gardenlinux/gardenlinux/blob/016c3889e20cb4bd937da4338f88c380cd9a49be/bin/find-build-container-for) script to find the correct container image. +# after +version_suffix=gl1+bp2150 +``` -e.g. +When targeting an older Garden Linux release, you may also need to update the `.container` file to use the matching build container image. + +:::tip +Use the [`bin/find-build-container-for`](https://github.com/gardenlinux/gardenlinux/blob/016c3889e20cb4bd937da4338f88c380cd9a49be/bin/find-build-container-for) script to find the correct container image. ```bash bin/find-build-container-for 2150.0.0 @@ -65,23 +100,29 @@ ghcr.io/gardenlinux/repo-debian-snapshot@sha256:99f72494ab45d33958a0385054de4742 ::: -### Optional: Build Locally +### Optional: Build locally -To check if your package builds before pushing it, refer to the [local Build How-To](/how-to/packaging/local-build.md). +To verify your package builds before pushing, see the [Local Build How-To](/how-to/packaging/local-build.md). -### 4. Push the branch +### 4. Push to the release branch ```bash -git push origin +git push origin HEAD:rel-2150 ``` -If the action is set up to run on `push` (as in the basic example), this will trigger the build job. The job will detect that this is a new version and create the necessary tags and GitHub releases. +The workflow on `rel-2150` triggers on push. Because `version_suffix` is already set in `prepare_source`, the build system reads it, creates the tag `8.21.0-2gl1+bp2150`, and publishes the GitHub release automatically. + +:::info +On `rel-` branches, `release: true` does **not** need to be set in the workflow call. The `version_suffix` in `prepare_source` is sufficient for tag creation and release publishing. The `release: true` input is only needed on `main`, where no suffix is pre-set, to trigger auto-appending `gl0`. +::: ## Backporting examples +The examples below show how to configure `prepare_source` on a `rel-` branch for different source scenarios. In each case, work on the branch that corresponds to the target Garden Linux release (for example, `rel-1877` for GL 1877.x or `rel-2150` for GL 2150.x). + ### Backporting new upstream version not available (yet) on Salsa -When backporting a version not available (yet) in Debian salsa (e.g., OpenSSL 3.1.7), configure the `prepare_source` script as follows: +When backporting a version not available (yet) in Debian salsa (for example, OpenSSL 3.1.7 targeted at GL 1443.x), configure `prepare_source` on branch `rel-1443` as follows: ```bash version_orig=3.1.7 @@ -95,7 +136,7 @@ This configuration fetches source files from the upstream repository while using ### Backporting package already in nightly releases -For packages available in Debian testing and tracked in salsa (e.g., `jq` version `1.8.1`): +For packages available in Debian testing and tracked in salsa (for example, `jq` version `1.8.1` targeted at GL 1877.x), configure `prepare_source` on branch `rel-1877`: ```bash pkg=jq @@ -113,7 +154,7 @@ version_suffix=gl0+bp1877 Use this method only as a last resort when source code is not available in Debian salsa or when upstream sources differ significantly. In all other cases, this method is discouraged. ::: -For packages present in Garden Linux nightly snapshots but not in salsa (e.g., `sqlite3` version `3.46.1`): +For packages present in Garden Linux nightly snapshots but not in salsa (for example, `sqlite3` version `3.46.1` targeted at GL 1877.x), configure `prepare_source` on branch `rel-1877`: ```bash pkg=sqlite3 diff --git a/docs/how-to/github-actions.md b/docs/how-to/github-actions.md index 8b697ba..f3578fd 100644 --- a/docs/how-to/github-actions.md +++ b/docs/how-to/github-actions.md @@ -85,6 +85,42 @@ jobs: release: ${{ github.ref == 'refs/heads/main' }} ``` +## Release branches (`rel-*`) + +Each `package-*` repository uses a [multi-branch model and version suffixes](/explanation/packaging#Version-suffix-and-branch-model) to separate nightly development from stable release maintenance. + +### How the workflow differs on `rel-` branches + +There are two key differences compared to `main`: + +**1. The `release` input is always `false` for pushes to `rel-`.** + +The condition `${{ github.ref == 'refs/heads/main' }}` evaluates to `false` on a push to `rel-2150`. This is intentional: on `rel-` branches, the `version_suffix` is already set explicitly in `prepare_source` (for example, `version_suffix=gl0+bp2150`). The build system reads that suffix and creates the tag and GitHub release automatically, without needing `release: true` to append the suffix. + +**2. `build_dep` pins dependencies to the same `+bp` versions.** + +On `main`, [build dependencies](/how-to/packaging/build-dependencies) are not usually pinned. On a `rel-` branch, other packages may also exist only as backported `+bp` releases that are not in the default nightly apt repository. The `build_dep` input lists these explicit dependencies: + +```yaml +on: + push: + workflow_dispatch: + schedule: + - cron: "0 0 * * *" +jobs: + build: + uses: gardenlinux/package-build/.github/workflows/build.yml@main + with: + release: ${{ github.ref == 'refs/heads/main' }} + build_dep: | + gardenlinux/bp-package-ngtcp2 1.22.1-1gl0+bp2150 + gardenlinux/package-nghttp2 1.68.1-1gl0+bp2150 + gardenlinux/package-openssl 3.5.5-1gl21+bp2150 + gardenlinux/package-gnutls 3.8.13-1gl0+bp2150 +``` + +This example is taken from [`package-curl` on `rel-2150`](https://github.com/gardenlinux/package-curl/blob/e8f171157619e6ee39e75e42dab097e41eb32590/.github/workflows/build.yml). + ## Related topics diff --git a/docs/how-to/package-releases.md b/docs/how-to/package-releases.md index a826c7e..136aea1 100644 --- a/docs/how-to/package-releases.md +++ b/docs/how-to/package-releases.md @@ -24,6 +24,7 @@ github_source_path: docs/how-to/package-releases.md github_target_path: docs/how-to/releases/package-releases.md --- + # Creating package releases This guide explains how to create Garden Linux Package releases. @@ -40,16 +41,16 @@ Read the [Packaging Explanation](/explanation/packaging.md) to get familiar with ## Prerequisites -Before creating an OS release, ensure you have: +Before creating a package release, ensure you have: - Write access to the `gardenlinux/package-*` repositories -- `git` and `gh` CLI tool installed and configured +- `git` and `gh` CLI tools installed and configured ## Phase 0: Preparation ### Step 1: Decide what to include -In tier one, individual [packages](/explanation/packaging.md) will need updates based on e.g. recent CVEs. Check for potential upgrades in important packages, too: +In tier one, individual [packages](/explanation/packaging.md) will need updates based on recent CVEs or upstream releases. Check for potential upgrades in important packages: - golang - containerd @@ -60,269 +61,104 @@ In tier one, individual [packages](/explanation/packaging.md) will need updates - glibc - linux kernel -**For each package requiring an update**, we need to follow the [Package Backporting Guide](/how-to/packaging/backporting.md) later. +For each package requiring an update, follow the [Package Backporting Guide](/how-to/packaging/backporting.md). -1. Navigate to the respective `github.com/gardenlinux/package-{name}` repository -2. Create a new package release if needed (see [package-build documentation](/explanation/packaging.md) for details) -3. Note the new version tag for use in the APT repository release +1. Navigate to the respective `github.com/gardenlinux/package-` repository. +2. Create a new package release if needed — see [Package Backporting Guide](/how-to/packaging/backporting.md) for details. +3. Note the new version tag for use in the [APT Repository Release](/how-to/releases/apt-repos.md). The complexity of updating a package varies: -- **Simple**: Packages that rebuild Debian packages with minimal adaptions -- **Complex**: Packages with extensive adaptions that may not apply to newer versions, or packages built from upstream sources +- **Simple**: Packages that rebuild Debian packages with minimal adaptations. +- **Complex**: Packages with extensive adaptations that may not apply to newer versions, or packages built from upstream sources. These often require [patching](/how-to/packaging/patching.md) and may have special [build dependencies](/how-to/packaging/build-dependencies.md). For complex updates, thoroughly test the new package version before including it in a release. -## Phase 1: Creating the release - -### Step 1: Create APT repository release - -In tier two, the [APT repository](/explanation/repo-infrastructure.md) must be created before building OS images. - -**For Major Releases:** - -Major releases automatically create APT repositories via the nightly `update.yml` workflow in the `repo` repository. The workflow: - -- Collects latest package versions from all `package-*` repositories -- Creates a new Debian snapshot -- Generates `package-releases` and `.container` files -- Publishes the APT repository to S3 - -No manual action is required for major release APT repositories. - -**For Minor Releases:** - -Follow the complete guide: [Creating APT Repository Releases](/how-to/releases/apt-repos.md) - -Quick summary: - -1. Checkout the base APT repository release tag in the `repo` repository -2. Modify `package-releases` and `package-imports` files -3. Commit and create a new tag (e.g., `2150.1.0`) -4. Push the tag to trigger the build - -**Verify APT Repository:** - -- Wait for the `repo` workflow to complete successfully -- Verify the APT repository is published to S3 - -### Step 2: Build Garden Linux OS +:::tip +To permanently exclude a package from the repo - for example if it unwanted for some reason - use a [NULL release](/how-to/packaging/null-releases.md) instead of removing the package repository (`github.com/gardenlinux/package-`). +::: -Once the APT repository is ready, we can build the OS images in tier three: +## Phase 1: Creating the package release -**Checkout or Create Release Branch:** +### Step 1: Build the package -```bash -# For major releases, create a new release branch from main -git checkout main -git pull -git checkout -b rel-MAJOR -git push origin rel-MAJOR - -# For minor releases, checkout the existing release branch -git checkout rel-MAJOR -git pull -``` +Once you have made your changes in the `package-` repository, push the branch to GitHub and verify that the build workflow runs successfully. -**Update VERSION File:** +The build is triggered automatically on push if the workflow is configured accordingly. You can also trigger it manually: ```bash -# Edit the VERSION file to contain the new version -echo "MAJOR.MINOR.0" > VERSION +# Trigger the build workflow manually for a specific package repository on the main (nightly) branch +gh workflow -R gardenlinux/package- run build.yml --ref main -# Example for minor release: -echo "2150.1.0" > VERSION - -# Commit the change -git add VERSION -git commit -m "Bump version to MAJOR.MINOR.0" -git push origin rel-MAJOR +# Trigger the build workflow manually for a specific package repository on a release branch +gh workflow -R gardenlinux/package- run build.yml --ref rel-2150 ``` -**Trigger Build Workflow:** - -The build process varies depending on the Garden Linux version: - -**For releases 2016.0.0 and later (using [SemVer](/reference/glossary.html#semver)):** - -Use the [manual release workflow](https://github.com/gardenlinux/gardenlinux/actions/workflows/manual_release.yml): +Monitor the workflow: ```bash -# Using gh CLI: -gh workflow run "Build and publish a release" \ ---ref rel-MAJOR \ --f target=release \ --f version=MAJOR.MINOR.0 - -# Example: -gh workflow run "Build and publish a release" \ ---ref rel-2150 \ --f target=release \ --f version=2150.1.0 +# Watch the workflow status +gh run watch -R gardenlinux/package- ``` -Or via the GitHub UI: - -1. Go to [Actions → Build and publish a release](https://github.com/gardenlinux/gardenlinux/actions/workflows/manual_release.yml) -2. Click "Run workflow" -3. Select the `rel-MAJOR` branch -4. Set version to `MAJOR.MINOR.0` -5. Leave target `release` -6. Leave other parameters at defaults - -**For older releases (1443, 1592 using non-SemVer):** - -Use the [nightly workflow](https://github.com/gardenlinux/gardenlinux/actions/workflows/nightly.yml) with version parameter: - -```bash -# Using gh CLI: -gh workflow run nightly.yml \ ---ref rel-MAJOR \ --f version=MAJOR.MINOR - -# Example for 1443: -gh workflow run nightly.yml \ ---ref rel-1443 \ --f version=1443.3 -``` +Or check the GitHub Actions page for the package repository. -**Monitor the Build:** +For full details on how the GitHub Actions build workflow works, see [GitHub Actions Package Building](/how-to/packaging/github-actions.md). To build and verify the package locally before pushing, see [Local Package Building](/how-to/packaging/local-build.md). -- Watch the workflow progress in GitHub Actions -- Verify all build jobs complete successfully -- Check that artifacts are published +### Step 2: Verify the release was created -### Step 3: Create GitHub release +After a successful build with `release: true`, the workflow automatically creates a GitHub release with the appropriate version tag (for example, `3.5.5-1gl0+bp2150`). -After the build completes, create the official GitHub release page: +Confirm the release exists: ```bash -# Run from main branch (not the release branch!) -git checkout main - -# Using gh CLI: -gh workflow run "release page" \ ---ref main \ --f run_id= --f is_latest=true # if this is the latest major.minor.0 version - -# Example: -gh workflow run "release page" \ ---ref main \ --f run_id=23802291489 \ --f is_latest=true # if this is the latest major.minor.0 version +# List the latest releases for the package repository +gh release list -R gardenlinux/package- --limit 5 ``` -:::tip -Get the "Run ID" from the URL of the "Build and publish a release" workflow run, e.g. https://github.com/gardenlinux/gardenlinux/actions/runs/23802291489 -::: - -Or via the GitHub UI: - -1. Go to [Actions → release page](https://github.com/gardenlinux/gardenlinux/actions/workflows/manual_gh_release_page.yml) -2. Click "Run workflow" -3. Select `main` branch -4. Set Build workflow run ID to `BUILD-RUN-ID` (e.g. `23802291489`) +Check that: -:::warning -Always review the generated release notes before publishing, especially the "Changes" section. +- The expected version tag is present. +- The release contains `.deb` build artifacts. +- No build errors are shown in the workflow summary. -The "Changes" section lists: +### Step 3: Note the version tag -- Upgraded packages in the minor release -- Fixed CVEs - -This data is generated by [glvd](https://github.com/gardenlinux/glvd) and may not be perfect. Verify: - -- CVE fixes match your expectations -- Package upgrades are correctly listed -- No unexpected changes appear +Record the exact version tag from the GitHub release — for example, `3.5.5-1gl0+bp2150`. You will need this when updating the `package-releases` file in the next tier. +:::info +The version tag format is `-gl+bp`. See the [Packaging Explanation](/explanation/packaging.md) for details. ::: -**Tag Manifest for Non-SemVer Releases:** +## Verification -:::warning -For releases that do not use semantic versioning (e.g., `1877.5`), add an extra tag for compatibility with Gardener (especially for USI images). +After the package release is published, verify it is ready for inclusion in an APT repository release. -```bash -# Example: Tag 1877.5 as 1877.5.0 -oras tag ghcr.io/gardenlinux/gardenlinux:1877.5 1877.5.0 -``` - -::: - -### Step 4: [ONLY FOR MAJOR RELEASES] Create rel-MAJOR Branch in repo - -:::danger -This step only applies to new major releases, not minor releases. -::: - -Create a release branch in the `gardenlinux/repo` repository based on the new release tag: +### Check the GitHub release ```bash -cd /path/to/repo -git pull --tags -git checkout MAJOR.0.0 -git checkout -b rel-MAJOR -git push -u origin rel-MAJOR +# Show the release details +gh release view -R gardenlinux/package- ``` -Example: - -```bash -cd /path/to/repo -git pull --tags -git checkout 2150.0.0 -git checkout -b rel-2150 -git push -u origin rel-2150 -``` +Confirm that: -This branch is used for creating future minor releases of the APT repository. +- The release is marked as the latest (or the intended tag for a patch release). +- All expected `.deb` artifacts are attached. +- The release notes accurately reflect the changes. -### Step 5: Generate CPE file +### Test the package locally -Generate the Common Platform Enumeration (CPE) file for the new release: +Use the [Local Package Building](/how-to/packaging/local-build.md) guide to build from the release tag and install the resulting `.deb` in a test environment: ```bash -# Run from main branch -gh workflow run "Generate and upload CPE to a release" \ ---ref main \ --f version=MAJOR.MINOR.0 - -# Example: -gh workflow run "Generate and upload CPE to a release" \ ---ref main \ --f version=2150.1.0 +# Install the package in a test Garden Linux system to verify it works +dpkg -i __amd64.deb ``` -Or via GitHub UI: - -1. Go to [Actions → Generate and upload CPE](https://github.com/gardenlinux/gardenlinux/actions/workflows/cpe.yml) -2. Click "Run workflow" -3. Select `main` branch -4. Set version to `MAJOR.MINOR.0` - -### Step 6: Update Garden Linux documentation - -:::info -TODO: add steps on how to update the documentation -::: - -## Phase 2: Post-release work - -### Verify release completeness - -- Verify the GitHub release page is complete and accurate -- Check that all expected artifacts are attached to the release -- Confirm the CPE file was generated and uploaded -- Test installation using the new release - -### Notify stakeholders +## Next step -- Notify relevant teams about the new release -- Gardener OS Extension Team -- Update any documentation referencing supported versions +Once all required package releases are ready, proceed to [Creating APT Repository Releases](/how-to/releases/apt-repos.md) to include the updated packages in an APT repository release. ## Related topics