Release Process

Nantian Gateway follows semantic 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

Semantic Versioning

Nantian Gateway follows the Semantic Versioning 2.0.0 specification. The version number format is MAJOR.MINOR.PATCH:

Version Type	Changes	Example
PATCH	Bug fixes, security patches, no API compatibility changes	`v1.2.3` → `v1.2.4`
MINOR	New features, backward-compatible API extensions	`v1.2.0` → `v1.3.0`
MAJOR	Incompatible API changes, major architectural overhauls	`v1.x.x` → `v2.0.0`

Version Number Usage

Stable release: v1.2.3 — recommended for production use
Pre-release: v1.3.0-alpha.1, v1.3.0-beta.1, v1.3.0-rc.1 — feature preview and testing
Development build: v0.0.0-dev — built from the main branch

Support Policy

Nantian Gateway maintains security and critical bug fixes for the two most recent MINOR versions:

Version	Status	Support Until
`v1.3.x`	Current major version	3 months after the next MINOR release
`v1.2.x`	Maintenance	3 months after the next MINOR release
`v1.1.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

# Create a release branch
git checkout -b release/v1.3.0

# Update the version number
# Edit gateway/VERSION, write 1.3.0
echo "1.3.0" > gateway/VERSION

# Update the Helm Chart version
# Edit gateway/deploy/helm/nantian-gw/Chart.yaml
# Modify the version and appVersion fields

3. Update the Changelog

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

## [1.3.0] - 2024-06-15

### 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 v2.0.0

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

4. Commit and Create a Tag

# Commit the version changes
git add gateway/VERSION gateway/deploy/helm/ CHANGELOG.md
git commit -m "chore(release): prepare v1.3.0"

# Push to GitHub
git push origin release/v1.3.0

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

# After merging, create the tag on the main branch
git checkout main
git pull upstream main
git tag -a v1.3.0 -m "Release v1.3.0"
git push upstream v1.3.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 gateway/deploy/helm
helm package nantian-gw

# Update the Helm repository index
helm repo index . --url https://nantian-gw.github.io/charts

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

Pre-releases

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

# Alpha version — features may be incomplete
git tag -a v1.4.0-alpha.1 -m "Pre-release v1.4.0-alpha.1"

# Beta version — features are mostly complete, needs testing
git tag -a v1.4.0-beta.1 -m "Pre-release v1.4.0-beta.1"

# Release Candidate — candidate for final release
git tag -a v1.4.0-rc.1 -m "Pre-release v1.4.0-rc.1"

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/v1.2
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 v1.2.4 -m "Patch release v1.2.4"

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
Version numbers are updated (VERSION, Chart.yaml)
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/v1.2-to-v1.3.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