67 lines
1.9 KiB
Markdown
67 lines
1.9 KiB
Markdown
# 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.
|