gardenlinux · moritzkirchnersap · May 26, 2026 · ByteOtter · May 27, 2026 · ByteOtter
diff --git a/docs/explanation/package-sources.md b/docs/explanation/package-sources.md
@@ -57,6 +57,27 @@ Packages with native sources are used when:
 
 - The source code is developed and maintained by the Garden Linux developers, so Debian does not package it
 
+# Package Repository Conventions
+## naming
+If a package repository is called package-* and if it has the build.yml workflow then it will be built every night. Sometimes one doesn't want that and then the repository name is prefixed differently, most likely bp-package-something.
-If a package repository is called package-* and if it has the build.yml workflow then it will be built every night. Sometimes one doesn't want that and then the repository name is prefixed differently, most likely bp-package-something.
+If a package repository is called package-* and if it has the build.yml workflow then it will be built every night. In certain cases, this is not required so the repository name is prefixed differently, usually `bp-package-*`.
-If a package repository is called package-* and if it has the build.yml workflow then it will be built every night. Sometimes one doesn't want that and then the repository name is prefixed differently, most likely bp-package-something.
+If a package repository is called package-* and if it has the build.yml workflow then it will be built every night. In certain cases, this is not required so the repository name is prefixed differently, usually `bp-package-*`.
+
+## branches within package-* repositories
+Each package repository should have `rel-*` branches that relate to the Garden Linux version for which this package is being built. This is to ensure the correct versions are being built with the correct dependencies for the correct Garden Linux versions. For example `package-openssh` could be built in one version for Garden Linux 1877 and another version for Garden Linux 2150. This means there should be branches called `rel-1877` and `rel-2150`. Packages should never be built main. Although it is a convention and not enforced.
-Each package repository should have `rel-*` branches that relate to the Garden Linux version for which this package is being built. This is to ensure the correct versions are being built with the correct dependencies for the correct Garden Linux versions. For example `package-openssh` could be built in one version for Garden Linux 1877 and another version for Garden Linux 2150. This means there should be branches called `rel-1877` and `rel-2150`. Packages should never be built main. Although it is a convention and not enforced.
+Each package repository should have `rel-*` branches that relate to the Garden Linux version for which this package is being built. This ensures the correct versions are being built with the correct dependencies for the correct Garden Linux versions. For example `package-openssh` could be built in one version for Garden Linux 1877 and another version for Garden Linux 2150. This means there should be branches called `rel-1877` and `rel-2150`.
+
+ **Packages should never be built `main`**. Although this is a convention and not enforced.
-Each package repository should have `rel-*` branches that relate to the Garden Linux version for which this package is being built. This is to ensure the correct versions are being built with the correct dependencies for the correct Garden Linux versions. For example `package-openssh` could be built in one version for Garden Linux 1877 and another version for Garden Linux 2150. This means there should be branches called `rel-1877` and `rel-2150`. Packages should never be built main. Although it is a convention and not enforced.
+Each package repository should have `rel-*` branches that relate to the Garden Linux version for which this package is being built. This ensures the correct versions are being built with the correct dependencies for the correct Garden Linux versions. For example `package-openssh` could be built in one version for Garden Linux 1877 and another version for Garden Linux 2150. This means there should be branches called `rel-1877` and `rel-2150`.
+
+ **Packages should never be built `main`**. Although this is a convention and not enforced.
+
+Also important on the `rel-*` branches is the `.container` file
+
+## .container file
+which includes the hash of the Garden Linux repo at the day of the release of the Major Garden Linux release, for example:
-Also important on the `rel-*` branches is the `.container` file
-
-## .container file
-which includes the hash of the Garden Linux repo at the day of the release of the Major Garden Linux release, for example:
+## .container file
+
+A important part of the release process on `rel-*` branches is the respective `.container` file which is different on each branch.
+
+It includes the hash of the Garden Linux repo at the day of the release of the Major Garden Linux release, for example:
-Also important on the `rel-*` branches is the `.container` file
-
-## .container file
-which includes the hash of the Garden Linux repo at the day of the release of the Major Garden Linux release, for example:
+## .container file
+
+A important part of the release process on `rel-*` branches is the respective `.container` file which is different on each branch.
+
+It includes the hash of the Garden Linux repo at the day of the release of the Major Garden Linux release, for example:
+```$ wget -qO- "https://raw.githubusercontent.com/gardenlinux/repo/refs/tags/1877.0/.container"
+ghcr.io/gardenlinux/repo-debian-snapshot@sha256:0348e829222f0e62c61cb68e630f1766b62e4311303bc35b02cbd5c62a98abef
+$ wget -qO- "https://raw.githubusercontent.com/gardenlinux/repo/refs/tags/1877.1/.container"
+ghcr.io/gardenlinux/repo-debian-snapshot@sha256:0348e829222f0e62c61cb68e630f1766b62e4311303bc35b02cbd5c62a98abef
+$ wget -qO- "https://raw.githubusercontent.com/gardenlinux/repo/refs/tags/1877.2/.container"
+ghcr.io/gardenlinux/repo-debian-snapshot@sha256:0348e829222f0e62c61cb68e630f1766b62e4311303bc35b02cbd5c62a98abef```
+it is crucial to pin down the build environment in that way with which the package is being built. Otherwise packages from debian testing at the point of time of when a package is being built are being used. Which might even mean a package doesn't build anylonger without a code change or doesn't work within the same Garden Linux release any longer for example there could be a different `libc` version in debian testing at that point as opposed to at release time.
-it is crucial to pin down the build environment in that way with which the package is being built. Otherwise packages from debian testing at the point of time of when a package is being built are being used. Which might even mean a package doesn't build anylonger without a code change or doesn't work within the same Garden Linux release any longer for example there could be a different `libc` version in debian testing at that point as opposed to at release time.
+
+It is important to pin down the build environment with which the package is built. Otherwise, the build would use the most recent currently available version of the package from Debian testing. This might result in the package's custom patches not applying anymore or the package simply becoming incompatible with the Debian snapshot the target Garden Linux release is based on.
+
+For example, the most recent version of a package might require a more recent version of a system library like `libc` or a newer compiler which the target release - say Garden Linux 1877 - does not provide.
-it is crucial to pin down the build environment in that way with which the package is being built. Otherwise packages from debian testing at the point of time of when a package is being built are being used. Which might even mean a package doesn't build anylonger without a code change or doesn't work within the same Garden Linux release any longer for example there could be a different `libc` version in debian testing at that point as opposed to at release time.
+
+It is important to pin down the build environment with which the package is built. Otherwise, the build would use the most recent currently available version of the package from Debian testing. This might result in the package's custom patches not applying anymore or the package simply becoming incompatible with the Debian snapshot the target Garden Linux release is based on.
+
+For example, the most recent version of a package might require a more recent version of a system library like `libc` or a newer compiler which the target release - say Garden Linux 1877 - does not provide.
+
+
+
 ## Related Topics
 
 <RelatedTopics />