Skip to content

RELEASE_GUIDE.md

Latest commit

 

History

History
171 lines (119 loc) · 5.1 KB

RELEASE_GUIDE.md

File metadata and controls

171 lines (119 loc) · 5.1 KB
Raw

Release guide

This guide covers the practical release options for this project: Docker Hub, Python package releases, GitHub releases, and Helm chart packaging.

Should this project be pushed to Docker Hub?

A Docker image is a reasonable distribution format, but version 0.3.3 should be treated as experimental or internal until the Priority 0 items in PRODUCTION_REVIEW.md are resolved. The current Dockerfile provides a useful hardened baseline:

  • slim Python base image
  • non-root runtime user
  • installed console command: aks-ip-diagnostic
  • default command: --help

Before publishing, run the release gate:

python -m compileall -q src tests
pytest -q
ruff check src tests
bandit -r src -x tests
pip-audit

Then build and smoke-test the image locally:

docker build -t aks-ip-diagnostic:local .
docker run --rm aks-ip-diagnostic:local version
docker run --rm aks-ip-diagnostic:local --help

Docker Hub manual release

Replace <dockerhub-user> with your Docker Hub namespace and <version> with the project version.

export IMAGE_NAME=<dockerhub-user>/aks-ip-diagnostic
export VERSION=0.3.3

docker login

docker build -t ${IMAGE_NAME}:${VERSION} -t ${IMAGE_NAME}:latest .
docker run --rm ${IMAGE_NAME}:${VERSION} version

docker push ${IMAGE_NAME}:${VERSION}
docker push ${IMAGE_NAME}:latest

Docker Hub expects images to be tagged with a namespace/repository name before pushing. The Docker CLI uses docker push to upload the tagged image to the registry.

Docker Hub GitHub Actions release

For automated publishing, configure these repository secrets:

Secret Value
DOCKERHUB_USERNAME Docker Hub username or organization
DOCKERHUB_TOKEN Docker Hub access token

Also set repository variable PUBLISH_DOCKERHUB=true if you want the release workflow to publish Docker Hub images. Without that variable, the Docker publishing job is skipped.

Recommended tag strategy:

  • latest only for the newest stable release
  • semantic version tag, for example 0.3.3
  • optionally major/minor tag, for example 0.3

Do not publish every branch as latest. Publish only from Git tags or GitHub releases.

Is a Python package release necessary?

A Python package release is not strictly required if users will run only Docker. It is useful when users want to install the CLI directly with pip:

pip install aks-ip-diagnostic
aks-ip-diagnostic version

Package release makes sense when:

  • platform engineers want local CLI usage without Docker
  • CI jobs want to install the tool using pip
  • you want standard Python versioning and dependency management
  • you want the project to be discoverable outside the container image

If the tool is internal only, publish to a private package registry first. If it is public, use PyPI after validating on TestPyPI.

Python package release steps

Install release tools:

python -m pip install --upgrade build twine

Build the package:

rm -rf dist build *.egg-info
python -m build
python -m twine check dist/*

Publish to TestPyPI first:

python -m twine upload --repository testpypi dist/*

Install from TestPyPI in a clean environment:

python -m venv /tmp/aks-ip-diagnostic-test
source /tmp/aks-ip-diagnostic-test/bin/activate
python -m pip install --upgrade pip
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple aks-ip-diagnostic
aks-ip-diagnostic version

If TestPyPI works, publish to PyPI:

python -m twine upload dist/*

Twine is the standard PyPA-supported utility for uploading Python distribution files to package indexes such as PyPI.

Versioning checklist

For a release, update these together:

  • pyproject.toml → [project].version
  • src/aks_ip_diagnostic/__init__.py → __version__
  • charts/aks-ip-diagnostic/Chart.yaml → appVersion
  • charts/aks-ip-diagnostic/values.yaml → default image tag, if you want it pinned
  • README and docs examples, if the version is shown

Use semantic versioning:

Change type Example Version bump
bugfix/docs only test fix, README update patch: 0.3.0 → 0.3.3
backward-compatible feature new flag or output mode minor: 0.3.0 → 0.4.0
breaking CLI/report schema change changed JSON contract major: 1.0.0 → 2.0.0

GitHub release checklist

git status
git diff
git add .
git commit -m "Prepare v0.3.3 release"
git tag v0.3.3
git push origin main --tags

Attach these artifacts to the GitHub release if useful:

  • source ZIP/tarball generated by GitHub
  • Python dist/*.whl and dist/*.tar.gz
  • Helm chart package from helm package charts/aks-ip-diagnostic
  • links to Docker Hub image tags

Release readiness answer

Current state:

  • Docker image: suitable for internal testing after the full release gate passes; not yet a production support commitment.
  • Python package: suitable for clean-environment/TestPyPI validation.
  • Helm chart: experimental until durable report storage and identity guidance are implemented.
  • Public release: defer until the Priority 0 production-review items are resolved.