Change Management and Versioning

Purpose

This guide defines how GitOps changes, Helm upgrades, and manual interventions are recorded so that the homelab platform remains auditable and recoverable.

Source-of-truth records

Artifact	Scope	Required when
changelogs/fragments/*.yml	Per-change release-note input	Any change affects deployments, recovery posture, network exposure, storage, or platform behavior
changelogs/changelog.yaml	Machine-readable release-note history	Updated when a release is cut or when changelog data is refreshed
CHANGELOG.md at repository root	Generated human-readable release notes	Regenerated from antsibull metadata after release work
SERVICE_NAME/README.md	Fast local operator entry point for one deployment directory	A top-level deployment directory is created, migrated, re-scoped, or significantly reworked
docs/services/SERVICE_NAME.md	Service-specific architecture and deployment facts	A service is created, upgraded, reconfigured, migrated, or re-scoped
docs/runbooks/SERVICE_NAME.md	Operator procedure	Triage, recovery, DR, or maintenance steps change
Pull request description	Review context	Every change proposed through GitOps

SemVer policy for the homelab platform

The platform version describes the operational state represented by main, not the Kubernetes version of any individual cluster.

Version bump	Use for	Examples
Major	Breaking or high-risk platform contract changes	Switching ingress model, changing storage defaults, replacing Fleet with another controller, destructive namespace migration
Minor	Additive or non-breaking platform changes	Adding a new service, enabling a new cluster overlay, non-breaking chart upgrade, adding a backup workflow
Patch	Corrective or low-risk operational change	Fixing probes, tuning resources, rotating credentials, patching CVEs, correcting ingress annotations

Required workflow for GitOps changes

1. Make the manifest or values change in a feature branch.
2. Add or update a changelog fragment under changelogs/fragments/.
3. Update the local README in the affected top-level deployment directory when overlays, prerequisites, commands, or entry points changed.
4. Update the relevant service page if the deployment, dependency graph, configuration surface, or access path changed.
5. Update the relevant runbook if the operator procedure, rollback path, probe behavior, or recovery steps changed.
6. Open a pull request to dev with impact, rollback, and affected clusters clearly stated.
7. After promotion from dev to main, create or update the platform release tag if the change should be versioned as a release.

Required workflow for Helm upgrades

For any Helm-driven upgrade, document all four version dimensions if they exist:

• Application version
• Container image tag
• Helm chart version
• Configuration schema or values changes

The changelog entry should identify:

• Affected service and clusters
• Previous and new chart or app version
• Whether the upgrade is major, minor, or patch at the platform level
• Rollback path
• Any manual steps or migration windows

Author that information in the fragment file first. The generated root CHANGELOG.md is derived output.

Required workflow for manual interventions

Manual changes should be treated as exceptions, not a second operating model.

Allowed reasons include:

• Incident stabilization
• Emergency security remediation
• Cluster outage where GitOps is unavailable
• Time-sensitive rollback while the control plane is impaired

Required follow-up within one working day:

1. Record the intervention in a changelog fragment with source marked as manual intervention.
2. Update the affected runbook if the intervention exposed a missing procedure.
3. Reconcile the live change back into Git so the clusters are no longer drifting from the repository.
4. Regenerate CHANGELOG.md during the next release cycle and reference the recovery commit or hotfix pull request in the fragment or PR description.

Standard changelog structure

Use the antsibull section model configured in changelogs/config.yaml:

• Release Summary
• Major Changes
• Minor Changes
• Breaking Changes / Porting Guide
• Deprecated Features
• Removed Features (previously deprecated)
• Security Fixes
• Bugfixes
• Known Issues

Not every release needs every section. Empty sections should be omitted.

Standard changelog entry format

Use entries that are short but operationally meaningful. Each line should answer what changed, where, and what an operator should care about.

Example format:

- authelia on layer7 and homelab: upgraded Helm chart 0.9.6 -> 0.10.0, rotated OIDC client secret, and updated ingress annotations; rollback is the previous values file revision.

For manual interventions, append the source explicitly:

- longhorn on homelab: manually detached and reattached pvc-longhorn volume during node recovery, then reconciled manifests in commit <sha>; source: manual intervention.

Pull request checklist for change management

Every deployment PR should answer these questions before merge:

1. What service or platform layer changed?
2. Which clusters and namespaces are affected?
3. Is the change major, minor, or patch from a platform perspective?
4. Was a changelog fragment added?
5. Were README, service docs, and runbooks updated when behavior changed?
6. What is the rollback path?
7. Was any manual intervention required before or during rollout?

Release guidance

Suggested cadence:

• Patch releases as needed for hotfixes and low-risk corrections.
• Minor releases on a regular platform cadence, such as monthly or after a bundle of reviewed improvements.
• Major releases only when architecture contracts change and the migration plan is documented.

Each release should correspond to a clean main state and a reviewed changelog.

antsibull workflow

This repository follows the antsibull-style workflow for non-Ansible projects:

1. Add fragments to changelogs/fragments/ during normal feature work.
2. Lint fragments with make validate-changelog.
3. Cut a release with make release-changelog VERSION=X.Y.Z RELEASE_DATE=YYYY-MM-DD.
4. Regenerate the human-readable release notes with make generate-changelog.
5. Review both changelogs/changelog.yaml and CHANGELOG.md before tagging the release.