From d017d811a2ee7c55b8a3481604e2f18ab4567219 Mon Sep 17 00:00:00 2001
From: Marek Blaha <mblaha@redhat.com>
Date: Tue, 20 Jan 2026 13:52:21 +0100
Subject: [PATCH] Add documentation for the version_suffix config option

---
 docs/configuration/actions.md |  6 +++++-
 docs/configuration/index.md   | 33 +++++++++++++++++++++++++++++++--
 2 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/docs/configuration/actions.md b/docs/configuration/actions.md
index 6d74e58b9e..3b96b9e6a2 100644
--- a/docs/configuration/actions.md
+++ b/docs/configuration/actions.md
@@ -257,9 +257,13 @@ There are also action-specific environment variables, which you can see below.
 ### `fix-spec-file`
 
 * `PACKIT_PROJECT_VERSION` — current version of the project (coming from `git describe`)
+* `PACKIT_RPMSPEC_VERSION` — version that will be set in the specfile
+* `PACKIT_RPMSPEC_RELEASE` — value for spec file's `%release` field which packit would set
 * `PACKIT_PROJECT_COMMIT` — commit hash of the top commit
 * `PACKIT_PROJECT_ARCHIVE` — expected name of the archive
-* `PACKIT_RPMSPEC_RELEASE` — value for spec file's `%release` field which packit would set
+* `PACKIT_PROJECT_BRANCH` — branch from which the SRPM is built
+* `PACKIT_PROJECT_SNAPSHOTID` — snapshot identifier in format  
+`{current_time}.{sanitized_current_branch}{git_desc_suffix}`
 
 ### `create-archive`
 
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index da612905f5..387a1db6e8 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -205,18 +205,22 @@ of the missing archive in the lookaside cache.
 #### release_suffix
 
 (*templated string*) String that can be used to override the default release suffix
-generated by Packit. The suffix will be expanded, and you can use following variables:
+generated by Packit. The suffix will be expanded, and you can use the following variables:
 
 * `PACKIT_PROJECT_VERSION` - version from `git describe`
+* `PACKIT_RPMSPEC_VERSION` - version that will be set in the specfile
 * `PACKIT_RPMSPEC_RELEASE` - release from specfile
 * `PACKIT_PROJECT_COMMIT` - commit SHA from which the SRPM is built
+* `PACKIT_PROJECT_ARCHIVE` - expected name of the archive
 * `PACKIT_PROJECT_BRANCH` - branch from which the SRPM is built
+* `PACKIT_PROJECT_SNAPSHOTID` - snapshot identifier in format  
+`{current_time}.{sanitized_current_branch}{git_desc_suffix}`
 
 Example usage:
 
     release_suffix: "dev.{PACKIT_PROJECT_BRANCH}"
 
-When unset, default release suffix that is generated by Packit is following:
+When unset, the default release suffix generated by Packit is:
 
     {original_release_number}.{current_time}.{sanitized_current_branch}{git_desc_suffix}
 
@@ -237,6 +241,31 @@ If you don't want the release to be modified at all, see [update_release](#updat
 This option only applies to SRPM creation and doesn't affect [`propose_downstream`](#propose_downstream)
 and [`pull_from_upstream`](#pull_from_upstream) jobs.
 
+#### version_suffix
+
+(*templated string*) String to append to the Version field in the RPM spec file. This is particularly useful for creating post-release snapshots following RPM versioning conventions. Supports the same variable expansion as [release_suffix](#release_suffix).
+
+Example usage with post-release snapshot versioning (using caret notation):
+
+    version_suffix: "^{PACKIT_PROJECT_SNAPSHOTID}"
+
+This would transform a version like `1.2.3` into `1.2.3^20231120173257.main.24.gabc123`, following the
+[Snapshots section of the Fedora packaging guidelines](https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/#_snapshots).
+
+:::caution Avoid duplicate snapshot IDs
+
+When using `version_suffix` with `PACKIT_PROJECT_SNAPSHOTID`, consider disabling automatic Release updates to avoid duplicating the snapshot identifier in both fields (see [`update_release`](#update_release)):
+
+    version_suffix: "^{PACKIT_PROJECT_SNAPSHOTID}"
+    update_release: false
+
+This updates Version with the snapshot suffix while preserving the Release from your spec file.
+
+:::
+
+This option only applies to SRPM creation and doesn't affect [`propose_downstream`](#propose_downstream)
+and [`pull_from_upstream`](#pull_from_upstream) jobs.
+
 #### files_to_sync
 
 (*list of strings or dicts*) A list of relative paths to files in the upstream