Release Process

Nantian Gateway follows calendar versioning, distributes binaries and container images through GitHub Releases, and distributes deployment packages through the Helm Chart repository. This page explains the complete release process for maintainers.

Versioning Policy

Calendar Versioning

Nantian Gateway follows Calendar Versioning (CalVer) with the format vYYYY.MM.PATCH:

Version Type	Changes	Example
PATCH	Bug fixes, security patches, no API compatibility changes	`v2026.06.0` → `v2026.06.1`
MONTHLY	New features, backward-compatible API extensions	`v2026.06.0` → `v2026.07.0`
YEARLY	Incompatible API changes, major architectural overhauls	`v2026.12.0` → `v2027.01.0`

Version Number Usage

Stable release: v2026.06.0 — recommended for production use
Pre-release: v2026.07.0-rc.1, v2026.07.0-rc.2, v2026.07.0-rc.3 — feature preview and testing
Development build: v0.0.0-dev — built from the main branch

The project is split across component repositories. A stable release uses one product version such as v2026.07.0 for the controlplane, dataplane, and dashboard image tags. The Helm chart uses chart version 2026.07.0 and records the product version in appVersion: "v2026.07.0". Development image tags such as latest, sha-*, and ci-* are for validation and should not replace stable release tags.

Support Policy

Nantian Gateway maintains security and critical bug fixes for the two most recent monthly releases:

Version	Status	Support Until
`v2026.07.x`	Current release	3 months after the next monthly release
`v2026.06.x`	Maintenance	3 months after the next monthly release
`v2026.05.x`	End of life	No longer supported

Release Artifacts

Each release produces the following artifacts:

Artifact	Description	Format
Control plane binary	Go-compiled static binary	`tar.gz` (Linux amd64/arm64)
Data plane binary	Rust-compiled static binary	`tar.gz` (Linux amd64/arm64)
Control plane container image	Distroless-based Docker image	`ghcr.io/nantian-gw/nantian-controlplane`
Data plane container image	Distroless-based Docker image	`ghcr.io/nantian-gw/dataplane`
Admin console image	Next.js-compiled static site	`ghcr.io/nantian-gw/dashboard`
Helm Chart	Deployment package	`tgz` format
Source archive	Full source code tar.gz	`tar.gz`

Release Workflow

1. Preparation

# Ensure you're on the main branch with the latest code
git checkout main
git pull upstream main

# Confirm all CI checks pass
# Check GitHub Actions: https://github.com/nantian-gw/gateway/actions

# Confirm conformance tests pass
make test-conformance

2. Create a Release Branch

product_version=v2026.07.0
chart_version=${product_version#v}

# Create release branches in the component repositories
git checkout -b release/${product_version}

# Coordinate the split repositories for this product version:
# - controlplane image: ghcr.io/nantian-gw/nantian-controlplane:${product_version}
# - dataplane image: ghcr.io/nantian-gw/dataplane:${product_version}
# - dashboard image: ghcr.io/nantian-gw/dashboard:${product_version}
# - chart version: ${chart_version}
# - chart appVersion: ${product_version}

Update helm-charts/charts/nantian-gw/Chart.yaml so version equals the chart version and appVersion equals the product version. Keep the component image tags aligned with the same product version for stable releases.

3. Update the Changelog

Add the new version’s change record to CHANGELOG.md. Use the following format:

## [2026.07.0] - 2026-07-01

### Added
- feat(controlplane): support HTTPRoute backend protocol selection
- feat(dataplane): add Ollama AI provider support
- feat(crd): add BackendLBPolicy CRD

### Fixed
- fix(dataplane): fix SNI matching in TLS passthrough
- fix(controlplane): fix port conflict on multi-listener Gateways

### Changed
- refactor(dataplane): refactor HTTP route matching engine, 15% performance improvement

### Deprecated
- deprecation(proto): SecretRef field will be removed in v2027.01.0

### Security
- security: fix input validation flaw in gRPC service (CVE-2024-XXXX)

4. Commit and Create a Tag

product_version=v2026.07.0

# Commit the release changes in each affected component repository
git add CHANGELOG.md
git commit -m "chore(release): prepare v2026.07.0"
git push origin release/${product_version}

# Commit the Helm chart version and appVersion update in the helm-charts repository
git add charts/nantian-gw/Chart.yaml CHANGELOG.md
git commit -m "chore(chart): release v2026.07.0"
git push origin release/${product_version}

# Create a PR to merge into main
# On GitHub, create a Pull Request titled "Release v2026.07.0"

# After merging, create the tag on the main branch
git checkout main
git pull upstream main
git tag -a v2026.07.0 -m "Release v2026.07.0"
git push upstream v2026.07.0

5. GitHub Release

After the tag is pushed, GitHub Actions automatically triggers the release process:

Build the control plane and data plane binaries
Build and push container images to ghcr.io
Package the Helm Chart
Create a GitHub Release and upload all artifacts

After the release is complete, add release notes to the GitHub Release page, including the changelog and upgrade notes.

6. Publish the Helm Chart

# Package the Helm Chart
cd helm-charts
helm package charts/nantian-gw

# Update the Helm repository index
helm repo index . --url https://chart.nantian.dev

# Push to the Helm Chart repository
git add .
git commit -m "chore(chart): release v2026.07.0"
git push

Pre-releases

For features that need community testing, you can publish pre-release versions:

# Release Candidate versions
git tag -a v2026.08.0-rc.1 -m "Pre-release v2026.08.0-rc.1"
git tag -a v2026.08.0-rc.2 -m "Pre-release v2026.08.0-rc.2"
git tag -a v2026.08.0-rc.3 -m "Pre-release v2026.08.0-rc.3"

Pre-release versions are marked as “Pre-release” on GitHub and won’t appear as the default “Latest Release”.

Patch Releases

For bugs that need urgent fixes, create a patch release from the corresponding release branch:

# Create from the release branch
git checkout release/v2026.06
git checkout -b fix/critical-bug

# After fixing the bug, cherry-pick to main
git checkout main
git cherry-pick <commit-hash>

# Create a patch tag
git tag -a v2026.06.1 -m "Patch release v2026.06.1"

Release Checklist

Confirm the following before releasing:

All CI checks pass (Go test, Rust test, lint, e2e)
Gateway API conformance tests pass
Changelog is updated with all user-facing changes
Product version, chart version, and Chart.yaml appVersion are coordinated
Container images are pushed to ghcr.io
Helm Chart is packaged and pushed
Documentation for the corresponding version is updated
Upgrade guide is updated (if there are breaking changes)
Release notes are written, including upgrade notes

Upgrade Compatibility

For MINOR and MAJOR versions, provide an upgrade guide covering:

Removed or deprecated API fields
Behavioral changes (e.g., default value changes)
New required configuration items
Data migration steps (if any)

Upgrade guides go in the docs/upgrade/ directory, named by version, e.g., docs/upgrade/v2026.06-to-v2026.07.md.

Next Steps

See Testing Guide to understand the CI pipeline
See Development Setup to learn about local builds
See Contributing Overview to understand the full contribution workflow