diff --git a/content/guides/component_guide.md b/content/guides/component_guide.md
index e6b3734686298cb351cf611de38d05460aad9254..be04955b982f92d55ff2cbc9bb89708a30c4a2d6 100644
--- a/content/guides/component_guide.md
+++ b/content/guides/component_guide.md
@@ -21,8 +21,6 @@ release a package:
repository or snapshot repository, depending on the release state of the
component.
-
-
## License scans
As contributors submit merge requests to packaged software, the CI pipeline performs
@@ -75,7 +73,6 @@ under `debian/apertis/copyright`, updating the merge request when necessary.
[Dpkg::Copyright::Scanner]: https://manpages.debian.org/testing/libconfig-model-dpkg-perl/Dpkg::Copyright::Scanner.3pm.en.html
[gitignore]: https://manpages.debian.org/testing/git-man/gitignore.5.en.html
-
## Custom pipelines
When using the packaging pipeline, developers cannot put their CI/CD automation
@@ -150,6 +147,55 @@ This is the process to import a new package from Debian to Apertis:
to the main archive](#landing-downstream-changes-to-the-main-archive) above to
publish the package on OBS.
+# Updating existing components
+
+## Pulling updates or security fixes from upstream distributions
+
+Updates coming from upstream can be pulled it by triggering a CI pipeline on a
+branches like `debian/buster` or `debian/bullseye`.
+
+The pipeline will check the Debian archive for updates, pull them in the
+`debian/$RELEASE`-like branch (for instance, `debian/bullseye` or
+`debian/bullseye-security`), try to merge the new contents with the matching
+`apertis/*` branches and, if successful, push a
+proposed updates branch while creating a Merge Request for each `apertis/*`
+branches it should be landed on.
+
+The upstream update pipeline is usually triggered from
+[the infrastructure dashboard](https://infrastructure.pages.apertis.org/dashboard/)
+but can be manually triggered from the GitLab web UI by selecting the
+`Run Pipeline` button in the `Pipelines` page of each repository under `pkg/*`
+and selecting the `debian/bullseye` branch as the reference.
+
+
+
+If the needed `debian/$RELEASE` branch doesn't exist (for example, there is a
+`debian/buster` branch but no `debian/bullseye`), the Gitlab Web UI can be used
+to create it. In the `Create from` field of the branch creation page, users
+should select `debian/${RELEASE-1}`. In this case, the new branch named
+`debian/bullseye` will be created from `debian/buster`.
+
+Reviewers can then force-push to the proposed update branch in the Merge
+Request to fixup any issue caused by the automated merge, and ultimately land
+the MRs to the `apertis/*` branches.
+
+In some situations the automated merge machinery may ask to
+`PLEASE SUMMARIZE remaining Apertis Changes`, and in that case
+reviewers should:
+* check out the proposed update branch
+* edit the changelog to list **all** the downstream changes the package still
+ ships compared to the newly merged upstream package and their reason,
+ describing the purpose of each downstream patch and of any other change
+ shown by `git diff` against the `debian/*` branch
+* amend the merge commit
+* force-push to the proposed update branch
+* land the associated Merge Requests as described above
+
+Remember to check that the updated package gets included in the next daily
+reference image build and wait for its [QA test
+results](https://lavaphabbridge.apertis.org/) to catch regressions timely
+and act accordingly.
+
## Adding updates from a non-default upstream repository of a distribution
There are circumstances, when we deviate from the default upstream. This usually happens
@@ -279,56 +325,6 @@ is not released into any of the Debian releases. In such case, we can try:
* Use the `pristine-lfs` tool to import the source package generated from the Debian repository into Apertis packaging repository. Eg. `pristine-lfs import-dsc libgpiod-1.4.2-1.dsc`
* Note: The `import-dsc` subcommand imports the new tarball into the git repository and commits it to the `pristine-lfs` branch. While a user can commit to the branch manually by-hand, we recommend the use of `import-dsc` to import new tarballs and committing them to the packaging repository
-
-# Updating existing components
-
-## Pulling updates or security fixes from upstream distributions
-
-Updates coming from upstream can be pulled it by triggering a CI pipeline on a
-branches like `debian/buster` or `debian/bullseye`.
-
-The pipeline will check the Debian archive for updates, pull them in the
-`debian/$RELEASE`-like branch (for instance, `debian/bullseye` or
-`debian/bullseye-security`), try to merge the new contents with the matching
-`apertis/*` branches and, if successful, push a
-proposed updates branch while creating a Merge Request for each `apertis/*`
-branches it should be landed on.
-
-The upstream update pipeline is usually triggered from
-[the infrastructure dashboard](https://infrastructure.pages.apertis.org/dashboard/)
-but can be manually triggered from the GitLab web UI by selecting the
-`Run Pipeline` button in the `Pipelines` page of each repository under `pkg/*`
-and selecting the `debian/bullseye` branch as the reference.
-
-
-
-If the needed `debian/$RELEASE` branch doesn't exist (for example, there is a
-`debian/buster` branch but no `debian/bullseye`), the Gitlab Web UI can be used
-to create it. In the `Create from` field of the branch creation page, users
-should select `debian/${RELEASE-1}`. In this case, the new branch named
-`debian/bullseye` will be created from `debian/buster`.
-
-Reviewers can then force-push to the proposed update branch in the Merge
-Request to fixup any issue caused by the automated merge, and ultimately land
-the MRs to the `apertis/*` branches.
-
-In some situations the automated merge machinery may ask to
-`PLEASE SUMMARIZE remaining Apertis Changes`, and in that case
-reviewers should:
-* check out the proposed update branch
-* edit the changelog to list **all** the downstream changes the package still
- ships compared to the newly merged upstream package and their reason,
- describing the purpose of each downstream patch and of any other change
- shown by `git diff` against the `debian/*` branch
-* amend the merge commit
-* force-push to the proposed update branch
-* land the associated Merge Requests as described above
-
-Remember to check that the updated package gets included in the next daily
-reference image build and wait for its [QA test
-results](https://lavaphabbridge.apertis.org/) to catch regressions timely
-and act accordingly.
-
## Maintaining package from upstream sources
There are likely to be instances where it is desirable to import the latest version of a piece of software into Apertis directly from it's original authors or maintainers.
@@ -540,7 +536,6 @@ updating the package and submit a merge request from there.
# Creating new modifications
-
The standard [Contribution Process]({{< ref "contributions.md" >}})
applies unchanged to packaging repositories, the Apertis development team and
trusted contributors push changes to `wip/` branches and get them landed to the