From 65ad6c91ea757a8293096f7846bceaecd405554e Mon Sep 17 00:00:00 2001
From: Walter Lozano <walter.lozano@collabora.com>
Date: Mon, 20 Jan 2025 13:54:20 -0300
Subject: [PATCH 1/2] rebasing: Rename mentions to old releases

To avoid confusions change the prefix OLD_ to CUR_ when pointing to the
current Apertis and Debian release.

Signed-off-by: Walter Lozano <walter.lozano@collabora.com>
---
 content/guides/maintenance/rebasing.md | 28 +++++++++++++-------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/content/guides/maintenance/rebasing.md b/content/guides/maintenance/rebasing.md
index cb3f8c61b..60a8c2bbb 100644
--- a/content/guides/maintenance/rebasing.md
+++ b/content/guides/maintenance/rebasing.md
@@ -22,11 +22,11 @@ more information about this policy.
 
 The following terms will be used here:
 
-- `OLD_DEV_RELEASE`: The existing Apertis release on which the new release will
+- `CUR_DEV_RELEASE`: The existing Apertis release on which the new release will
   be based.
 - `NEW_DEV_RELEASE`: The new Apertis development release that we are creating
   during the rebasing process.
-- `OLD_DEBIAN_RELEASE`: The Debian release on which `OLD_DEV_RELEASE` is based.
+- `CUR_DEBIAN_RELEASE`: The Debian release on which `CUR_DEV_RELEASE` is based.
 - `NEW_DEBIAN_RELEASE`: The Debian release on which `NEW_DEV_RELEASE` will be
   based.
 
@@ -68,8 +68,8 @@ flagged by OBS. The aim here is to reduce the time required when rebasing.
 
 During the rebase `NEW_DEV_RELEASE` will be unstable as many packages will be
 updated and images will not be generated. To allow development work during this
-time, `OLD_DEV_RELEASE` will be used as development branch. For that reason,
-after `OLD_DEV_RELEASE` freeze ends, it will be used for development.
+time, `CUR_DEV_RELEASE` will be used as development branch. For that reason,
+after `CUR_DEV_RELEASE` freeze ends, it will be used for development.
 {{% notice note %}}
 For repositories that diverge during the rebase cycle, after the rebase is
 completed, changes will need forward porting to `NEW_DEV_RELEASE`.
@@ -81,19 +81,19 @@ completed, changes will need forward porting to `NEW_DEV_RELEASE`.
 1. Create `NEW_DEV_RELEASE` branch for `apertis-docker-images`
 1. Tweak the `package-source-builder` dockerfile in the `NEW_DEV_RELEASE`
    release to enable Debian `NEW_DEBIAN_RELEASE`
-1. Enable apertis `OLD_DEV_RELEASE` repositories in dockerfile, to allow
+1. Enable apertis `CUR_DEV_RELEASE` repositories in dockerfile, to allow
    the installation of Apertis specific packages, such as `apertis-dev-tools`
 1. Temporarily disable other docker images as they won't be needed
 1. Create new OBS projects for `NEW_DEV_RELEASE`
 1. Disable publish of `NEW_DEV_RELEASE` on OBS projects
 1. Add `NEW_DEBIAN_RELEASE` DoD on `NEW_DEV_RELEASE` OBS repositories
 1. Create Apertis `NEW_DEV_RELEASE` branches for the repositories in the
-   following groups based on the `OLD_DEV_RELEASE` branches in Gitlab. (This
+   following groups based on the `CUR_DEV_RELEASE` branches in Gitlab. (This
    should create new branches but not trigger any pipelines): 
    - [infrastructure](https://gitlab.apertis.org/infrastructure)
    - [tests](https://gitlab.apertis.org/tests)
    - [sample-applications](https://gitlab.apertis.org/sample-applications)
-1. Continue to use `OLD_DEV_RELEASE` for development work. 
+1. Continue to use `CUR_DEV_RELEASE` for development work. 
 
 # Perform Rebase
 
@@ -114,14 +114,14 @@ It is better to process the list of packages in batches, starting with a small n
    [`create-branches`](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/create-branches)
    script:
    ```
-   $ ./create-branches --filter pkg/${pkg} --branch-prefix debian --new-release ${NEW_DEBIAN_RELEASE} --base-release ${OLD_DEBIAN_RELEASE}
+   $ ./create-branches --filter pkg/${pkg} --branch-prefix debian --new-release ${NEW_DEBIAN_RELEASE} --base-release ${CUR_DEBIAN_RELEASE}
    ```
 1. Create `upstream/NEW_DEBIAN_RELEASE` branches in Gitlab for these packages
    in their git repositories. This can also be done using the
    [`create-branches`](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/create-branches)
    script:
    ```
-   $ ./create-branches --filter pkg/${pkg} --branch-prefix upstream --new-release ${NEW_DEBIAN_RELEASE} --base-release ${OLD_DEBIAN_RELEASE}
+   $ ./create-branches --filter pkg/${pkg} --branch-prefix upstream --new-release ${NEW_DEBIAN_RELEASE} --base-release ${CUR_DEBIAN_RELEASE}
    ```
 
 1. Trigger the pipeline on the `debian/NEW_DEBIAN_RELEASE` branches using the
@@ -240,20 +240,20 @@ Keep track of delta introduced as this will need to be documented, rectified or
    ```
 1. Drop these packages from the new release:
    - Remove the `apertis/NEW_DEV_RELEASE` branch from the package in Gitlab
-   - Set the default branch as `apertis/OLD_DEV_RELEASE` using
+   - Set the default branch as `apertis/CUR_DEV_RELEASE` using
      [set-delete-branches](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/set-delete-branches).
    - Update
      [gitlab-rulez](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/gitlab-scripts/rulez.yaml)
-     to contain a list for `OLD_DEV_RELEASE` containing the packages for which
+     to contain a list for `CUR_DEV_RELEASE` containing the packages for which
      it is the last release. This causes gitlab-rulez to leave the default
      branch at this release for these packages.
 
 ## K. Forward port any changes to OLD\_DEV\_RELEASE
 
-1. Check which repositories have diverged between `OLD_DEV_RELEASE` and
-`NEW_DEV_RELEASE`. This means for repositories where `OLD_DEV_RELEASE` is not a
+1. Check which repositories have diverged between `CUR_DEV_RELEASE` and
+`NEW_DEV_RELEASE`. This means for repositories where `CUR_DEV_RELEASE` is not a
 descendant of `NEW_DEV_RELEASE` and thus further changes have been merged to
-`OLD_DEV_RELEASE`.
+`CUR_DEV_RELEASE`.
 1. Evaluate and prepare forward ports for changes where required.
 1. Fix any temporary workarounds that were added during rebasing.
 
-- 
GitLab


From 90ec5a693d4ee142b276b4d34e5b2412b20b60ca Mon Sep 17 00:00:00 2001
From: Walter Lozano <walter.lozano@collabora.com>
Date: Mon, 20 Jan 2025 13:57:07 -0300
Subject: [PATCH 2/2] rebasing: Update guide

After the initial work in the rebase, update the documentation to show the
approach taken.

Signed-off-by: Walter Lozano <walter.lozano@collabora.com>
---
 content/guides/maintenance/rebasing.md | 44 ++++++++++++++------------
 1 file changed, 24 insertions(+), 20 deletions(-)

diff --git a/content/guides/maintenance/rebasing.md b/content/guides/maintenance/rebasing.md
index 60a8c2bbb..c27ae3e2c 100644
--- a/content/guides/maintenance/rebasing.md
+++ b/content/guides/maintenance/rebasing.md
@@ -22,7 +22,7 @@ more information about this policy.
 
 The following terms will be used here:
 
-- `CUR_DEV_RELEASE`: The existing Apertis release on which the new release will
+- `CUR_DEV_RELEASE`: The current Apertis release on which the new release will
   be based.
 - `NEW_DEV_RELEASE`: The new Apertis development release that we are creating
   during the rebasing process.
@@ -37,8 +37,18 @@ Q1.
 
 ## A. Test Rebase Workflow
 
-1. Follow the rebase plan, but with a limited set of packages from target using
-   `NEW_DEV_RELEASE` set to `rebase-test`.
+1. Follow the rebase plan, but with a limited set of packages from target, forking
+   them in a new namespace, such as `pkg-rebase-trixie`.
+1. Create a MR `wip/xxx/rebase-preparation` in `apertis-docker-images` to draft the changes to be used during
+   the rebase.
+1. Tweak the `package-source-builder` dockerfile in the `NEW_DEV_RELEASE`
+   release to enable Debian `NEW_DEBIAN_RELEASE`
+1. Enable apertis `CUR_DEV_RELEASE` repositories in dockerfile, to allow
+   the installation of Apertis specific packages, such as `apertis-dev-tools`
+1. Temporarily disable other docker images as they won't be needed
+1. Create new OBS projects for `pkg-rebase-trixie`
+1. Disable publish of `pkg-rebase-trixie` on OBS projects
+1. Add `NEW_DEBIAN_RELEASE` DoD on `pkg-rebase-trixie` OBS repositories
 1. Check that pipelines run as expected
 1. Check that the scripts used to check status work as expected
 
@@ -47,7 +57,7 @@ It is not required to merge all the changes, focus on ensuring that the
 workflow is working as expected.
 {{% /notice %}}
 
-## B. Test Debian Sources
+## B. Prepare package lists
 
 If sufficient time is available early in Q1, it is advantageous to ensure that
 we have a relatively accurate seed list and have already imported new
@@ -57,10 +67,8 @@ flagged by OBS. The aim here is to reduce the time required when rebasing.
 
 1. Use [germinate](https://gitlab.apertis.org/infrastructure/germinate) to
    generate seeds for `NEW_DEBIAN_RELEASE`.
-1. Compare "existing-packages" lists generated for `NEW_DEBIAN_RELEASE` with
-   the list of packages in the current Apertis release. Review differences and
-   update the new seed list as required.
-1. Review packages listed in "new-packages" lists for addition to Apertis
+1. Follow the instructions in the repository to update the seed list and blacklist
+   to allow smoother rebase process with fewer iterations.
 
 # Preparing for Rebase
 
@@ -70,20 +78,16 @@ During the rebase `NEW_DEV_RELEASE` will be unstable as many packages will be
 updated and images will not be generated. To allow development work during this
 time, `CUR_DEV_RELEASE` will be used as development branch. For that reason,
 after `CUR_DEV_RELEASE` freeze ends, it will be used for development.
+
 {{% notice note %}}
 For repositories that diverge during the rebase cycle, after the rebase is
 completed, changes will need forward porting to `NEW_DEV_RELEASE`.
 {{% /notice %}}
 
-
 ## D. Prepare Infrastructure
 
-1. Create `NEW_DEV_RELEASE` branch for `apertis-docker-images`
-1. Tweak the `package-source-builder` dockerfile in the `NEW_DEV_RELEASE`
-   release to enable Debian `NEW_DEBIAN_RELEASE`
-1. Enable apertis `CUR_DEV_RELEASE` repositories in dockerfile, to allow
-   the installation of Apertis specific packages, such as `apertis-dev-tools`
-1. Temporarily disable other docker images as they won't be needed
+1. Merge the changes in `wip/xxx/rebase-preparation` into `NEW_DEV_RELEASE` branch
+   for `apertis-docker-images`
 1. Create new OBS projects for `NEW_DEV_RELEASE`
 1. Disable publish of `NEW_DEV_RELEASE` on OBS projects
 1. Add `NEW_DEBIAN_RELEASE` DoD on `NEW_DEV_RELEASE` OBS repositories
@@ -125,10 +129,10 @@ It is better to process the list of packages in batches, starting with a small n
    ```
 
 1. Trigger the pipeline on the `debian/NEW_DEBIAN_RELEASE` branches using the
-   [`trigger-pipeline`](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/gitlab/trigger-pipeline)
+   `trigger-pipeline` function from [manage-repo]](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/manage-repo)
    script:
    ```
-   $ ./trigger-pipeline ${pkg} debian/${NEW_DEBIAN_RELEASE}
+   $ ./release-scripts/manage-repo trigger-pipeline ${pkg} debian/${NEW_DEBIAN_RELEASE}
    ```
    This will trigger a chain of pipelines that will sync with the branch with
    the required Debian release and attempt to merge with the `NEW_DEV_RELEASE`
@@ -152,7 +156,7 @@ should be checked in the following order:
 - Other packages, such as those in `development` and `sdk`.
 
 The
-[analise-rebases.py](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/analyse-rebases.py)
+[analyse-rebases.py](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/rebase-scripts/analyse-rebases.py)
 script can be used to aid with this process.
 
 There will be different scenarios depending on the package:
@@ -205,8 +209,8 @@ Keep track of delta introduced as this will need to be documented, rectified or
    [analyse-missing.py](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/analyse-missing-packages.py)
 1. Check if all build statuses are green on OBS
 1. Check that OBS is NOT using Debian DoD to build packages using the
-   [`check-for-dod`](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/release-scripts/check-for-dod) script.
-1. Drop Bookworm DoD repositories from OBS
+   [`check-for-dod`](https://gitlab.apertis.org/infrastructure/apertis-infrastructure/-/blob/main/rebase-scripts/check-for-dod) script.
+1. Drop Debian DoD repositories from OBS
 1. Fix any leftover cracks:
    * New package imports
    * Build dependency trimming
-- 
GitLab