Skip to content

Commit a44c29b

Browse files
CybotTMCybotTM
committed
docs(version): align doc.go with template-driven ldflag forwarding
Copilot review on #565 pointed out that internal/version/doc.go still described ldflags as being applied directly to internal/version.*, contradicting the new main.* + forwardBuildMetadata flow in cmd/ldap-manager/main.go. Rewrite the package docstring to describe: - The shared go-app template as the canonical ldflag source (-X main.version, main.build, main.buildTime) - forwardBuildMetadata() as the init-time bridge into internal/version.Version / .CommitHash / .BuildTimestamp - The local-dev default behavior (defaults preserved when shim vars are empty) Also drop the obsolete Makefile / Dockerfile examples — the new release pipeline replaces both paths with the shared template, so those snippets were actively misleading. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
1 parent 1797362 commit a44c29b

1 file changed

Lines changed: 37 additions & 68 deletions

File tree

‎internal/version/doc.go‎

Lines changed: 37 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -2,33 +2,42 @@
22
//
33
// # Overview
44
//
5-
// This package manages application version metadata that is injected at build time using Go's -ldflags.
6-
// It provides three key pieces of information: semantic version, git commit hash, and build timestamp.
5+
// This package holds the three user-facing build metadata values —
6+
// semantic version, git commit hash, and build timestamp — that the
7+
// application reports via FormatVersion() and the `version` / `--version`
8+
// subcommands.
79
//
8-
// # Build-Time Injection
10+
// # Build-Time Injection (template-driven)
911
//
10-
// Version information is injected during the build process using -ldflags to set package-level variables:
12+
// Release builds use the shared go-app release pipeline
13+
// (netresearch/.github/templates/go-app/.github/workflows/release.yml),
14+
// which passes these ldflags to every matrix entry:
1115
//
12-
// go build -ldflags="\
13-
// -X 'github.com/netresearch/ldap-manager/internal/version.Version=v1.0.8' \
14-
// -X 'github.com/netresearch/ldap-manager/internal/version.CommitHash=$(git rev-parse --short HEAD)' \
15-
// -X 'github.com/netresearch/ldap-manager/internal/version.BuildTimestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)' \
16-
// " ./cmd/ldap-manager
16+
// -X main.version=<tag>
17+
// -X main.build=<commit-sha>
18+
// -X main.buildTime=<commit-timestamp>
1719
//
18-
// The Makefile automates this process:
20+
// cmd/ldap-manager/main.go declares matching package-level variables
21+
// (`var version, build, buildTime string`) and calls
22+
// forwardBuildMetadata() at init() time to copy their values into
23+
// Version, CommitHash, and BuildTimestamp here. The indirection keeps
24+
// the fleet ldflag convention (`main.*`) uniform across every go-app
25+
// consumer while still letting this package expose structured
26+
// package-level identifiers.
1927
//
20-
// make build # Production build with version injection
21-
// make build-dev # Development build (Version="dev")
28+
// Local development builds (plain `go build ./cmd/ldap-manager`) leave
29+
// the shim vars empty; the defaults "dev"/"n/a"/"n/a" below are
30+
// preserved unchanged.
2231
//
2332
// # Package Variables
2433
//
2534
// Three package-level variables store build metadata:
2635
//
2736
// - Version: Semantic version string (e.g., "v1.0.8") or "dev" for development builds
28-
// - CommitHash: Short git commit SHA (e.g., "a4d1aae") or "n/a" if not available
29-
// - BuildTimestamp: ISO 8601 build timestamp (e.g., "2025-09-30T21:41:41Z") or "n/a"
37+
// - CommitHash: git commit SHA (e.g., "a4d1aae") or "n/a" if not available
38+
// - BuildTimestamp: ISO 8601 build timestamp (e.g., "2026-04-20T17:58:00Z") or "n/a"
3039
//
31-
// Default values ("dev", "n/a", "n/a") are used for development builds when -ldflags are not provided.
40+
// Default values ("dev", "n/a", "n/a") are used for development builds when no ldflags are provided.
3241
//
3342
// # Usage
3443
//
@@ -41,11 +50,11 @@
4150
//
4251
// func main() {
4352
// log.Info().Str("version", version.FormatVersion()).Msg("Starting LDAP Manager")
44-
// // Output (production): Starting LDAP Manager version=v1.0.8 (a4d1aae, built at 2025-09-30T21:41:41Z)
53+
// // Output (production): Starting LDAP Manager version=v1.0.8 (a4d1aae, built at 2026-04-20T17:58:00Z)
4554
// // Output (development): Starting LDAP Manager version=Development version
4655
// }
4756
//
48-
// Add version endpoint for monitoring:
57+
// Version endpoint for monitoring:
4958
//
5059
// func versionHandler(c *fiber.Ctx) error {
5160
// return c.JSON(fiber.Map{
@@ -57,35 +66,17 @@
5766
//
5867
// # FormatVersion Function
5968
//
60-
// The FormatVersion() function provides human-readable version strings:
69+
// FormatVersion() returns a human-readable version string:
6170
//
62-
// // Development build (no -ldflags)
71+
// // Development build (no ldflags)
6372
// version.Version = "dev"
6473
// version.FormatVersion() // Returns: "Development version"
6574
//
66-
// // Production build (with -ldflags)
75+
// // Release build (ldflags applied via main.* -> forwardBuildMetadata)
6776
// version.Version = "v1.0.8"
6877
// version.CommitHash = "a4d1aae"
69-
// version.BuildTimestamp = "2025-09-30T21:41:41Z"
70-
// version.FormatVersion() // Returns: "v1.0.8 (a4d1aae, built at 2025-09-30T21:41:41Z)"
71-
//
72-
// # Makefile Integration
73-
//
74-
// The project Makefile handles version injection automatically:
75-
//
76-
// # Extract version from git tags
77-
// VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
78-
// COMMIT_HASH := $(shell git rev-parse --short HEAD 2>/dev/null || echo "n/a")
79-
// BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
80-
//
81-
// # Build with version injection
82-
// build:
83-
// @echo "Building version $(VERSION)..."
84-
// @go build -ldflags="\
85-
// -X 'github.com/netresearch/ldap-manager/internal/version.Version=$(VERSION)' \
86-
// -X 'github.com/netresearch/ldap-manager/internal/version.CommitHash=$(COMMIT_HASH)' \
87-
// -X 'github.com/netresearch/ldap-manager/internal/version.BuildTimestamp=$(BUILD_TIME)' \
88-
// " -o bin/ldap-manager ./cmd/ldap-manager
78+
// version.BuildTimestamp = "2026-04-20T17:58:00Z"
79+
// version.FormatVersion() // Returns: "v1.0.8 (a4d1aae, built at 2026-04-20T17:58:00Z)"
8980
//
9081
// # Version String Format
9182
//
@@ -107,37 +98,15 @@
10798
// 5. Release notes and changelog generation
10899
// 6. CI/CD pipeline integration for deployment tracking
109100
//
110-
// # Docker Builds
111-
//
112-
// For Docker images, version is injected at build time:
113-
//
114-
// # In Dockerfile
115-
// ARG VERSION=dev
116-
// ARG COMMIT_HASH=n/a
117-
// ARG BUILD_TIME=n/a
118-
//
119-
// RUN go build -ldflags="\
120-
// -X 'github.com/netresearch/ldap-manager/internal/version.Version=${VERSION}' \
121-
// -X 'github.com/netresearch/ldap-manager/internal/version.CommitHash=${COMMIT_HASH}' \
122-
// -X 'github.com/netresearch/ldap-manager/internal/version.BuildTimestamp=${BUILD_TIME}' \
123-
// " ./cmd/ldap-manager
124-
//
125-
// # Build with version
126-
// docker build \
127-
// --build-arg VERSION=v1.0.8 \
128-
// --build-arg COMMIT_HASH=$(git rev-parse --short HEAD) \
129-
// --build-arg BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
130-
// -t ldap-manager:v1.0.8 .
131-
//
132101
// # Best Practices
133102
//
134-
// 1. Always use semantic versioning for Version field (e.g., v1.0.8, not 1.0.8)
103+
// 1. Always use semantic versioning for Version (e.g., v1.0.8, not 1.0.8)
135104
// 2. Include git commit hash for precise build identification
136105
// 3. Use ISO 8601 format for timestamps (YYYY-MM-DDTHH:MM:SSZ)
137-
// 4. Automate version injection in CI/CD pipelines
138-
// 5. Never hard-code version strings in source code
139-
// 6. Include version in application logs at startup
140-
// 7. Expose version via health check endpoint for monitoring
106+
// 4. Never hard-code version strings in source code
107+
// 5. Include version in application logs at startup
108+
// 6. Expose version via health check endpoint for monitoring
141109
//
142-
// For more details on build process, see: docs/development/contributing.md
110+
// For release pipeline details, see:
111+
// https://github.com/netresearch/.github/blob/main/templates/go-app/.github/workflows/release.yml
143112
package version

0 commit comments

Comments
 (0)