From 747c42499db84595dc701ad4b51f7e53ec16d63c Mon Sep 17 00:00:00 2001
From: Mikhail Chusavitin <mchusavitin@mchusmbp.local>
Date: Wed, 18 Mar 2026 17:49:55 +0300
Subject: [PATCH] Add build version display contract

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../build-version-display/contract.md         | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 rules/patterns/build-version-display/contract.md

diff --git a/rules/patterns/build-version-display/contract.md b/rules/patterns/build-version-display/contract.md
new file mode 100644
index 0000000..44daa68
--- /dev/null
+++ b/rules/patterns/build-version-display/contract.md
@@ -0,0 +1,66 @@
+# Contract: Build Version Display
+
+Version: 1.0
+
+## Purpose
+
+Every web application must display the current build version in the page footer so that users and support staff can identify exactly which version is running.
+
+---
+
+## Rule
+
+The build version **must** be visible in the footer on every page of the web application.
+
+---
+
+## Requirements
+
+- The version is shown in the footer on **all** pages, including error pages (404, 500, etc.).
+- The version string is injected at **build time** — it is never hardcoded in source and never fetched at runtime.
+- The version value comes from a single authoritative source (e.g. `package.json`, `version.go`, a CI environment variable). It is not duplicated manually.
+- Format: any human-readable string that uniquely identifies the build — a semver tag, a git commit SHA, or a combination (e.g. `1.4.2`, `1.4.2-abc1234`, `abc1234`).
+- The version text must be legible but visually subordinate — use a muted color and small font size so it does not compete with page content.
+
+---
+
+## Recommended implementation
+
+**Frontend (JS/TS build tools)**
+
+Expose the version through an environment variable at build time and reference it in the footer component:
+
+```ts
+// vite.config.ts / webpack.config.js
+define: {
+  __APP_VERSION__: JSON.stringify(process.env.APP_VERSION ?? "dev"),
+}
+
+// Footer component
+<footer>v{__APP_VERSION__}</footer>
+```
+
+**Go (server-rendered HTML)**
+
+Inject via `-ldflags` at build time and pass to the template:
+
+```go
+// main.go
+var Version = "dev"
+
+// Build: go build -ldflags "-X main.Version=1.4.2"
+```
+
+```html
+<!-- base template -->
+<footer>v{{ .Version }}</footer>
+```
+
+---
+
+## What is NOT allowed
+
+- Omitting the version from any page, including error pages.
+- Fetching the version from an API endpoint at runtime (network dependency for a static value).
+- Hardcoding a version string in source code.
+- Storing the version in more than one place.