From e6deb22bdb199fd8fb793f2920cd94013c85bcf5 Mon Sep 17 00:00:00 2001
From: Adam Williamson <awilliam@redhat.com>
Date: Mar 01 2024 22:54:25 +0000
Subject: Koji doc: discourage use of direct chained builds


Direct chained builds really aren't a good idea any more, now we
create updates for all Rawhide builds and apply gating tests to
some. If a build in the chain fails gating tests it will not be
pushed stable and the chain will fail.

This explains that, but also explains that you can use
`chain-build --target` to do a chain build to a side tag, and
this might be a nice workflow.

Signed-off-by: Adam Williamson <awilliam@redhat.com>

---

diff --git a/modules/ROOT/pages/Using_the_Koji_Build_System.adoc b/modules/ROOT/pages/Using_the_Koji_Build_System.adoc
index 654c657..959aefc 100644
--- a/modules/ROOT/pages/Using_the_Koji_Build_System.adoc
+++ b/modules/ROOT/pages/Using_the_Koji_Build_System.adoc
@@ -57,21 +57,32 @@ fedpkg build --target 'f{NEXTOSVER}-python'
 
 [#chained_builds]
 ==== Chained builds
-WARNING: chain-builds only work when building on rawhide.
-To chain-build packages to update a released OS version,
-https://fedoraproject.org/wiki/Bodhi/BuildRootOverrides[set up an override using bodhi]
-requesting packages to be included in the proper buildroot.
-
 Sometimes you want to make sure
 that one build has succeeded before launching the next one,
 for example when you want to rebuild a package
 against a dependency that has just been rebuilt.
-In that case, use a chain build with:
+`fedpkg` provides a `chain-build` command to help with this.
+As explained in xref:Package_Update_Guide.adoc#multiple_packages[the Package Update Guide],
+multi-build chains like this should be created on a side tag,
+and you can use `fedpkg chain-build` to do the builds on the side tag.
+
+To do a chained build to a side tag, first create the side tag,
+as explained in the Package Update Guide. In the simplest case,
+just do:
+
+....
+fedpkg request-side-tag
+....
+
+This will print a command you can use to wait for the side tag to be created.
+Run that command, and when it exits, do:
 
 ....
-fedpkg chain-build libwidget libgizmo
+fedpkg chain-build --target=side-tag-name libwidget libgizmo
 ....
 
+replacing `side-tag-name` with the actual name of your side tag.
+
 The current package is added to the end of the CHAIN list.
 Colons (`:`) can be used in the CHAIN parameter to define groups of packages.
 Packages in any single group will be built in parallel
@@ -81,7 +92,7 @@ before the next group will begin building.
 For example:
 
 ....
-fedpkg chain-build libwidget libaselib : libgizmo :
+fedpkg chain-build --target=side-tag-name libwidget libaselib : libgizmo :
 ....
 
 causes `libwidget` and `libaselib` to be built in parallel,
@@ -94,6 +105,22 @@ If a build fails,
 following builds are canceled,
 but the builds that already succeeded are pushed to the repository.
 
+*Note:* It is possible to do a chained build
+directly to the default build target for Rawhide,
+but this is no longer recommended or reliable.
+Building for the default Rawhide target immediately auto-creates an update,
+and some Rawhide updates are now subject to gating tests.
+If any package in the chain is subject to gating tests, and one fails,
+that package will never reach _stable_
+and the rest of the chain will not be able to build.
+This is quite likely to happen to chains containing critical path packages.
+When using a side tag, no updates will be automatically created,
+and each build is immediately available in the side tag's buildroot
+without having to pass tests first.
+You can manually create the update once all the builds are done,
+and the tests will not encounter dependency issues
+if you rebuilt all the dependent packages correctly.
+
 [#scratch_builds]
 === Scratch Builds