From 25a368100a98213119a06085f9c7f535521721da Mon Sep 17 00:00:00 2001
From: David Gibson <david@gibson.dropbear.id.au>
Date: Tue, 26 May 2026 19:32:39 +1000
Subject: [PATCH] docs: Improvements to release creation tooling

Introduce prepare-release for the deterministic parts of preparing a
release.  Update AGENTS.md to use that, rather than using an LLM for
deterministic steps.

finalize-release now pushes the release commit and tag after signing, and
prepares a release announcement mail.

Assisted-by: Claude:claude-opus-4-6i
Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
---
 AGENTS.md                | 28 +++++++---------
 scripts/finalize-release | 27 ++++++++++++++++
 scripts/prepare-release  | 70 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+), 16 deletions(-)
 create mode 100755 scripts/prepare-release

diff --git a/AGENTS.md b/AGENTS.md
index 77fa0f6..82d5996 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -94,20 +94,14 @@ Releases use the `vMAJOR.MINOR.PATCH` tag format (e.g., `v1.7.2`).
 An AI agent can prepare the release; the human maintainer reviews,
 adds `Signed-off-by`, and signs the tag.
 
-1. **Update `VERSION.txt`** — change the single line to the new version
-   number (e.g., `1.7.2`). `meson.build` reads its version from this
-   file. No other version files need editing.
-
-2. **Draft the version bump commit** — create the commit *without*
-   `Signed-off-by` (agents must not add S-o-b per the AI contribution
-   policy). Use the message format:
+1. **Update `VERSION.txt` and commit** — run the prepare script:
+   ```sh
+   scripts/prepare-release X.Y.Z
    ```
-   Bump version to vX.Y.Z
+   This updates `VERSION.txt` and creates the version bump commit
+   (without `Signed-off-by`, per the AI contribution policy).
 
-   Prepare for a new release.
-   ```
-
-3. **Draft the tag message** — write it to a temporary file (e.g.,
+2. **Draft the tag message** — write it to a temporary file (e.g.,
    `tag-message.txt`) for the maintainer to review. The format is:
    ```
    DTC X.Y.Z
@@ -121,16 +115,18 @@ adds `Signed-off-by`, and signs the tag.
    fdtoverlay, Build, General, etc.) with a bullet per notable change.
    Generate the changelog from `git log vPREV..HEAD`.
 
-4. **Human review** — the maintainer reviews the commit and tag
+3. **Human review** — the maintainer reviews the commit and tag
    message, then runs the finalize script which amends the commit to
-   add `Signed-off-by` and creates the signed annotated tag:
+   add `Signed-off-by`, creates the signed annotated tag, pushes the
+   release commit and tag to origin, and optionally uploads to
+   kernel.org via kup:
    ```sh
    scripts/finalize-release tag-message.txt
    ```
 
 Agents must **never** run `scripts/finalize-release` or
-`scripts/kup-dtc`. These perform signing and upload operations that
-only a human maintainer may execute.
+`scripts/kup-dtc`. These perform signing, push, and upload operations
+that only a human maintainer may execute.
 
 ## Coding Conventions
 
diff --git a/scripts/finalize-release b/scripts/finalize-release
index 8b6fba3..89008f2 100755
--- a/scripts/finalize-release
+++ b/scripts/finalize-release
@@ -61,6 +61,10 @@ echo "Created signed tag $TAG."
 echo "Review with: git show $TAG"
 echo ""
 
+git push origin main "$TAG"
+git push github main "$TAG"
+git push gitlab main "$TAG"
+
 SCRIPTDIR=$(dirname "$0")
 
 printf "Upload to kernel.org via kup? [y/N] "
@@ -69,3 +73,26 @@ case "$answer" in
 	y|Y) "$SCRIPTDIR/kup-dtc" "$VERSION" ;;
 	*) echo "Skipping kup upload." ;;
 esac
+
+TAG_BODY=$(git tag -l --format='%(contents:body)' "$TAG")
+
+ANNOUNCE="announce-${TAG}.txt"
+cat > "$ANNOUNCE" <<MAIL
+To: devicetree-compiler@vger.kernel.org
+Subject: DTC $VERSION released
+
+DTC $VERSION is now available.
+
+Git tree:
+  https://git.kernel.org/pub/scm/utils/dtc/dtc.git
+
+Tagged release ($TAG):
+  https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tag/?h=$TAG
+
+Tarball:
+  https://kernel.org/pub/software/utils/dtc/dtc-${VERSION}.tar.gz
+
+$TAG_BODY
+MAIL
+
+echo "Announcement draft written to $ANNOUNCE"
diff --git a/scripts/prepare-release b/scripts/prepare-release
new file mode 100755
index 0000000..0e5acf3
--- /dev/null
+++ b/scripts/prepare-release
@@ -0,0 +1,70 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Prepare a release: update VERSION.txt and create the version bump
+# commit.  This handles steps 1 and 2 of the release procedure in
+# AGENTS.md.  Step 3 (drafting the tag message) requires judgement to
+# categorise and summarise changes, so is left to the caller.
+
+set -e
+
+usage() {
+	echo "Usage: $0 <version>" >&2
+	echo "" >&2
+	echo "  version   X.Y.Z or vX.Y.Z" >&2
+	echo "" >&2
+	echo "Example: $0 1.8.1" >&2
+	exit 1
+}
+
+RAW="$1"
+if [ -z "$RAW" ]; then
+	usage
+fi
+
+VERSION="${RAW#v}"
+
+case "$VERSION" in
+	[0-9]*.[0-9]*.[0-9]*)
+		;;
+	*)
+		echo "Error: version '$VERSION' does not look like X.Y.Z" >&2
+		exit 1
+		;;
+esac
+
+TAG="v${VERSION}"
+
+if git rev-parse "$TAG" >/dev/null 2>&1; then
+	echo "Error: tag $TAG already exists" >&2
+	exit 1
+fi
+
+if ! git diff-index --quiet HEAD; then
+	echo "Error: working tree is dirty; commit or stash first" >&2
+	exit 1
+fi
+
+echo "$VERSION" > VERSION.txt
+git add VERSION.txt
+git commit -m "$(cat <<EOF
+Bump version to $TAG
+
+Prepare for a new release.
+EOF
+)"
+
+echo "Building with make..."
+git clean -fdx
+make check
+
+echo ""
+echo "Building with meson..."
+git clean -fdx
+meson setup build
+meson test -C build
+
+echo ""
+echo "All builds and tests passed."
+echo "Next: draft the tag message to tag-message.txt, then run:"
+echo "  scripts/finalize-release tag-message.txt"