From d0cee4f00549a1b9193dff5071a0d126a6725372 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vin=C3=ADcius=20Ferr=C3=A3o?=
 <2031761+viniciusferrao@users.noreply.github.com>
Date: Fri, 21 Aug 2026 09:27:05 -0300
Subject: [PATCH] docs(genesis): document release packaging

---
 BUILD.md                       | 26 +++++++++++++++
 genesis-openembedded/README.md | 59 ++++++++++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 genesis-openembedded/README.md

diff --git a/BUILD.md b/BUILD.md
index 43fd88f..263b847 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -76,6 +76,11 @@ Use these flags to skip specific operations:
   - Skips `createrepo --update`.
 - `--skip-tarball`
   - Skips tarball creation for both binary and SRPM repos.
+- `--skip-genesis`
+  - Skips the existing per-EL Genesis image build.
+- `--genesis-release <PATH>`
+  - Adds a verified OpenEmbedded Genesis RPM release and skips the existing
+    per-EL Genesis image build for that run.
 - `--scrub-all-chroots`
   - Runs `mock -r <TARGET> --scrub=all` before build and collection.
 - `--collect-dir <PATH>`
@@ -147,6 +152,27 @@ Notes:
 - Add `--skip-install` to skip those checks.
 - `<RUN_ID>` is optional; when omitted it is timestamp-based.
 
+# Add an OpenEmbedded Genesis Release
+
+Build the Genesis package release first, following
+[`genesis-openembedded/README.md`](genesis-openembedded/README.md). Then pass the
+result to the regular repository build:
+
+```bash
+cd <REPO_ROOT>
+perl ./mockbuild-all.pl \
+  --repo-root <REPO_ROOT> \
+  --xcat-source <XCAT_SOURCE> \
+  --genesis-release /path/to/xcat-genesis-release
+```
+
+The release is checked before any package is collected. Its RPMs and SRPMs are
+copied into each generated EL repository. Old Genesis packages are removed from
+those output directories so a previous run cannot satisfy the release by
+accident.
+
+Omit `--genesis-release` to keep using the existing Genesis builder.
+
 # Build Unified Repository Without xCAT (`--skip-xcat`)
 
 Use this mode to build dependency packages only and skip invoking `/root/xcat-dep/xcat-source-code/buildrpms.pl`.
diff --git a/genesis-openembedded/README.md b/genesis-openembedded/README.md
new file mode 100644
index 0000000..a10ab6b
--- /dev/null
+++ b/genesis-openembedded/README.md
@@ -0,0 +1,59 @@
+# OpenEmbedded Genesis packages
+
+xCAT builds the Genesis image in `xcat-core`. This directory turns those build
+outputs into packages and feeds them into the xcat-dep repositories.
+
+Run the release builder on a host that can build the OpenEmbedded layer. The
+xcat-core checkout must be clean. `--xcat-ref` checks that the checkout points
+to the intended commit; it does not change the checkout for you.
+
+```bash
+./genesis-openembedded/build \
+  --xcat-source /path/to/xcat-core \
+  --xcat-ref <tag-or-commit> \
+  --all \
+  --output-dir /path/to/xcat-genesis-release
+```
+
+The default format is `all`, which produces RPM, SRPM, and DEB packages. Use
+`--format rpm` or `--format deb` when only one package family is needed. The
+supported image architectures are `x86`, `x86_64`, `ppc64`, `ppc64le`,
+`armv7hf`, `aarch64`, and `riscv64`.
+
+Each package installs one exact-architecture image under
+`/opt/xcat/share/xcat/netboot/genesis/<architecture>/`. The packages themselves
+are `noarch` or `all` because they are installed on the management node, not run
+on the target node.
+
+The release directory contains:
+
+- `rpm/`, `srpm/`, and `deb/` package directories
+- `release.manifest`, including the xcat-core commit
+- `SHA256SUMS`
+
+Validate the directory before publishing it:
+
+```bash
+./genesis-openembedded/verify-release /path/to/xcat-genesis-release
+```
+
+Pass that same directory to the repository builders:
+
+```bash
+perl ./mockbuild-all.pl \
+  --genesis-release /path/to/xcat-genesis-release \
+  [other build options]
+
+./build-apt-repo.sh \
+  --genesis-release /path/to/xcat-genesis-release \
+  [DIST ...]
+```
+
+The RPM builder skips its old per-EL Genesis build when a release is supplied.
+The APT builder adds the DEB packages to every selected suite. Both consumers
+verify package identities and checksums before collecting packages.
+
+Without `--genesis-release`, both builders keep their existing behavior. This
+allows the package publishing change to land before xcat-core starts depending
+on the new architecture-specific package names. Generated images and packages
+belong in release storage, not in Git.