From de3fe4893befb51936171ea48754820a16bfbf8b Mon Sep 17 00:00:00 2001
From: Guillaume Tauzin <4648633+gtauzin@users.noreply.github.com>
Date: Sun, 26 Jul 2026 12:45:36 +0200
Subject: [PATCH] docs(release): document signing release tags with gitsign

Resolves the deferred signed-tags item (7.1) via the documented-gitsign approach:
maintainers sign release tags with keyless Sigstore (gitsign) when they create them,
keeping the developer-driven push-a-tag release flow intact. Updates the generated
projects' release how-to and the template repo's own release-process doc with git tag -s
and the one-time gitsign config. Complements the PEP 740 artifact attestations.
---
 docs/pages/explanation/release-process.md      |  2 +-
 template/docs/pages/how-to/contribute.md.jinja | 14 ++++++++++++--
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/docs/pages/explanation/release-process.md b/docs/pages/explanation/release-process.md
index e699a35..c6c21f3 100644
--- a/docs/pages/explanation/release-process.md
+++ b/docs/pages/explanation/release-process.md
@@ -62,7 +62,7 @@ The version is determined by the Git tag - there is no version file to manually
 
 ## The Complete Flow in Practice
 
-1. Developer pushes a version tag: `git tag v0.2.0 -m "Release v0.2.0" && git push origin v0.2.0`
+1. Developer pushes a **signed** version tag: `git tag -s v0.2.0 -m "Release v0.2.0" && git push origin v0.2.0` (tags are signed with [gitsign](https://github.com/sigstore/gitsign) keyless Sigstore signing, so the tag is verifiable with no long-lived GPG key; this complements the artifact-level PEP 740 attestations)
 2. `changelog.yml` generates the changelog, builds the package, creates a PR
 3. Maintainer reviews and merges the PR
 4. `publish-release.yml` creates a GitHub Release with artifacts
diff --git a/template/docs/pages/how-to/contribute.md.jinja b/template/docs/pages/how-to/contribute.md.jinja
index 6fa1589..25e5120 100644
--- a/template/docs/pages/how-to/contribute.md.jinja
+++ b/template/docs/pages/how-to/contribute.md.jinja
@@ -694,13 +694,23 @@ graph LR
 
 ### How It Works
 
-1. **Tag a release:**
+1. **Tag a release** (signed with [gitsign](https://github.com/sigstore/gitsign) keyless Sigstore signing):
 
     ```bash
-   git tag v0.2.0 -m "Release v0.2.0"
+   git tag -s v0.2.0 -m "Release v0.2.0"
    git push origin v0.2.0
     ```
 
+    One-time gitsign setup so `git tag -s` signs via Sigstore, with no long-lived GPG key to manage:
+
+    ```bash
+   git config --local gpg.x509.program gitsign
+   git config --local gpg.format x509
+   git config --local tag.gpgSign true
+    ```
+
+    The first signing authenticates via your identity provider in a browser; verify a tag with `gitsign verify-tag`. Signed tags complement the PEP 740 artifact attestations the publish workflow already produces, so both the tag and the published artifacts are verifiable.
+
 2. **Automated changelog workflow** (`changelog.yml`):
     - Generates changelog from conventional commits using git-cliff
     - Creates a **Pull Request** with the updated CHANGELOG.md