Template Versioning

This template follows Semantic Versioning to help users understand the impact of updates.

Version Format

MAJOR.MINOR.PATCH[-PRERELEASE]
Component When to Increment Example

MAJOR

Breaking changes to generated files or required answer changes

1.0.0 → 2.0.0

MINOR

New features, new optional prompts, non-breaking enhancements

1.0.0 → 1.1.0

PATCH

Bug fixes, typo corrections, documentation updates

1.0.0 → 1.0.1

Pre-release Suffixes

Suffix Purpose Example

-dev

Active development

1.0.0-dev

-alpha.N

Early testing

1.0.0-alpha.1

-beta.N

Feature complete, testing

1.0.0-beta.1

-rc.N

Release candidate

1.0.0-rc.1

(none)

Final release

1.0.0

Copier sorts these correctly per PEP 440:

1.2.0-dev < 1.2.0-alpha.1 < 1.2.0-beta.1 < 1.2.0-rc.1 < 1.2.0

VERSION File

The current version is stored in the VERSION file at the repository root. This file:

  • Provides human-readable version for CI scripts and documentation

  • Is read by bump-version.sh for version management

  • Should match the latest git tag for releases

Git Tags and Copier

Copier uses git tags for version resolution when users specify a version:

copier copy --vcs-ref=1.0.0 https://repo.git .

The VERSION file is for human/CI consumption; git tags are what Copier actually uses.

Using bump-version.sh

The scripts/bump-version.sh utility manages version updates:

# Show current version and usage
./scripts/bump-version.sh

# Bump versions
./scripts/bump-version.sh patch    # 1.0.0 → 1.0.1
./scripts/bump-version.sh minor    # 1.0.0 → 1.1.0
./scripts/bump-version.sh major    # 1.0.0 → 2.0.0

# Pre-release management
./scripts/bump-version.sh release  # 1.0.0-dev → 1.0.0 (remove suffix)
./scripts/bump-version.sh dev      # 1.0.0 → 1.1.0-dev (start next cycle)

# Set specific version
./scripts/bump-version.sh set 2.0.0-beta.1

# Create git tag from current version
./scripts/bump-version.sh tag

Breaking Change Examples

These require a MAJOR version bump:

  • Renaming a Copier variable (e.g., service_name → artifact_id)

  • Removing a question/variable that was previously required

  • Changing the structure of generated directories

  • Changing the answers file location

  • Modifying the type of an existing variable

Non-Breaking Change Examples

These require a MINOR or PATCH version:

  • Adding new optional questions with sensible defaults

  • Adding new generated files

  • Adding new Skaffold profiles

  • Fixing Jinja template bugs

  • Updating base image versions

  • Improving documentation

Using Specific Versions

# Use latest tagged version (recommended)
copier copy https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git .

# Use specific version
copier copy --vcs-ref v1.2.0 https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git .

# Use latest commit (bleeding edge)
copier copy --vcs-ref HEAD https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git .

# Update to specific version
copier update --vcs-ref v1.2.0 -a .copier-answers/devops.yaml

Checking Current Version

# Check VERSION file
cat VERSION

# Check git tags
git tag --list 'v*' | sort -V | tail -5

# Check what version a project was generated from
cat .copier-answers/devops.yaml | grep _commit