From aa56cca107b79d62f6323b0cb1f819e78f8a38cb Mon Sep 17 00:00:00 2001
From: Mike McLean <mikem@redhat.com>
Date: Mar 27 2026 17:54:15 +0000
Subject: Add volume toplink info to release notes


Fixes https://pagure.io/koji/issue/4556

---

diff --git a/docs/source/migrations/migrating_to_1.36.rst b/docs/source/migrations/migrating_to_1.36.rst
index 6dedf0b..b66ceeb 100644
--- a/docs/source/migrations/migrating_to_1.36.rst
+++ b/docs/source/migrations/migrating_to_1.36.rst
@@ -16,6 +16,36 @@ As in previous releases, we provide a migration script that updates the database
     # psql koji koji < /usr/share/koji/schema-upgrade-1.35-1.36.sql
 
 
+Volume toplinks
+---------------
+
+.. warning:: Action required for non-default volumes
+
+In order to address a previous issue with promoting builds, the system now
+requires that each volume directory contain a ``toplink`` symlink that points
+to the main volume.
+This is simply a symlink that points to the main volume. E.g.
+
+::
+
+     $ file /mnt/koji/vol/vol3/toplink
+     /mnt/koji/vol/vol3/toplink: symbolic link to /mnt/koji
+
+You **must** create this symlink for any existing volumes used in your system.
+Failure to do so can result in build promotion failures.
+
+We recommend using an absolute symlink, as in the example above.
+
+When adding a new volume, admins should create this symlink when they create
+the volume directory. If not, the hub will automatically create it using the
+configured topdir path and log a warning.
+
+For more information, see
+
+* :ref:`Fix draft symlink handling <draft-symlink-fix-1-36>`
+* :ref:`adding-new-volume`
+
+
 Notable configuration changes
 -----------------------------
 
diff --git a/docs/source/release_notes/release_notes_1.36.rst b/docs/source/release_notes/release_notes_1.36.rst
index 80d55aa..a3895d8 100644
--- a/docs/source/release_notes/release_notes_1.36.rst
+++ b/docs/source/release_notes/release_notes_1.36.rst
@@ -505,6 +505,8 @@ Since 1.31, Koji clients have used http headers to pass their session info.
 However, the hub has been misreading the callnum since that time.
 
 
+.. _draft-symlink-fix-1-36:
+
 **Fix draft symlink handling**
 
 | PR: https://pagure.io/koji/pull-request/4383
@@ -513,6 +515,23 @@ However, the hub has been misreading the callnum since that time.
 When a draft build is promoted, Koji maintains a symlink at the original location.
 These fixes address cases where the hub did not create that link.
 
+As part of this fix, the system now requires that each volume directory contain a
+``toplink`` symlink that points to the main volume.
+We recommend using an absolute symlink. E.g.
+
+::
+
+     $ file /mnt/koji/vol/vol3/toplink
+     /mnt/koji/vol/vol3/toplink: symbolic link to /mnt/koji
+
+When adding a new volume, admins should create this symlink when they create
+the volume directory. If not, the hub will automatically create it using the
+configured topdir path and log a warning.
+
+For *existing* volumes, admins **must** create this symlink for each
+preexisting volume during their migration to 1.36.
+Failure to do so can result in build promotion failures.
+
 
 **Fix listUsers type check**
 
diff --git a/docs/source/volumes.rst b/docs/source/volumes.rst
index 1645c38..6a65b5b 100644
--- a/docs/source/volumes.rst
+++ b/docs/source/volumes.rst
@@ -70,6 +70,8 @@ for builds on other volumes.
     /mnt/koji/packages/fake/1.0/21: symbolic link to ../../../vol/vol3/packages/fake/1.0/21
 
 
+.. _adding-new-volume:
+
 Adding a new volume
 -------------------