Proposal: add automated calendar-version tags to container image publishes

[guanzhousongmicrosoft]

Summary

The functional-tests container image currently publishes only a mutable :latest tag (plus sha-<hash> tags) on every push to main. Downstream consumers such as documentdb/documentdb need a way to pin to a known-good image version so that new tests landing here do not unexpectedly break CI pipelines in other repos.

This issue proposes adding automated version tags to every image publish.

Problem

The documentdb repo is wiring functional tests into its CI as a PR gate (documentdb/documentdb#566). Today it must reference ghcr.io/documentdb/functional-tests:latest, which means:

1. PRs can break without any code change. A new test added here for a feature DocumentDB does not yet support will cause every open PR in documentdb to fail the functional-test check.
2. No reproducibility. The same commit in documentdb can pass today and fail tomorrow because :latest moved.
3. Hard to audit. When failures appear, there is no human-readable tag to identify which version of the test suite caused them. The sha- tags are immutable but not ergonomic.

Proposed solution: automated calendar-version tags

Add an automatic tagging step to the existing docker-build.yml workflow so that every push to main produces a stable, human-readable version tag in addition to :latest.

Tag format

Calendar versioning (CalVer): vYYYY.MM.DD.N where N is a sequence number that increments if multiple pushes land on the same day.

Examples:

• v2026.04.10.1
• v2026.04.10.2 (second push that day)

Why CalVer over SemVer

• No release ceremony required. Tags are generated automatically on every merge -- no manual git tag or version bump PR needed.
• Self-documenting. The tag tells you exactly when the test content was published.
• Compatible with the existing docker/metadata-action setup. The workflow already handles type=semver patterns; CalVer tags like v2026.04.10.1 match the v*.*.* pattern and produce both the full tag and shorter prefix tags.

Implementation sketch

A minimal addition to docker-build.yml (or a separate workflow that runs after it):

- name: Generate CalVer tag
  if: github.ref == 'refs/heads/main'
  run: |
    date_prefix="$(date -u +%Y.%m.%d)"
    seq=1
    while git rev-parse "v${date_prefix}.${seq}" >/dev/null 2>&1; do
      seq=$((seq + 1))
    done
    tag="v${date_prefix}.${seq}"
    git tag "${tag}"
    git push origin "${tag}"

The existing docker/metadata-action with type=semver,pattern={{version}} will then produce image tags like ghcr.io/documentdb/functional-tests:v2026.04.10.1 automatically.

How downstream repos would use this

1. documentdb pins its CI to a specific CalVer tag (e.g., v2026.04.10.1).
2. A scheduled daily run in documentdb tests against :latest to discover new tests.
3. When the daily run surfaces new failures, a maintainer bumps the pin in a dedicated PR and updates the deselect list as needed.
4. PR authors in documentdb are never surprised by test-image changes they did not cause.

What stays the same

• :latest continues to be published on every push to main (no change).
• sha-<hash> tags continue to be published (no change).
• The build workflow logic is unchanged; only a tagging step is added.

Alternatives considered

Alternative	Why not preferred
Manual SemVer tags	Requires human coordination and release ceremony for a repo that merges multiple times per day
Pin to sha- tags in downstream	Works but is not human-readable; hard to tell which image version is in use at a glance
No versioning; downstream uses :latest and accepts breakage	Unacceptable for a PR gate -- contributors should not be blocked by unrelated test additions

Related

• Add documentdb-local functional test workflow documentdb#566 -- PR wiring functional tests into DocumentDB CI
• Functional test infrastructure: baseline tracking, CI gating, and developer workflow documentdb#567 -- Tracking issue for CI integration