💡 Automated Version Bumping & Continuous Package Publishing Standard

[don-petry]

Summary

Evaluate whether repositories that produce and publish packages (such as empower-personal-dashboard, broodminder-data, etc.) should automatically bump versions and publish releases on every merge to main, or retain the current version-gated model (where releases only publish when a version bump is explicitly merged). Define and register an Architecture Decision Record (ADR) in petry-projects/.github governing the release lifecycle, SemVer calculation, and whether to standardize this via a central reusable/vendored workflow in .github versus repository-specific implementations.

Problem Context & Signal

In package-producing repositories across the org (e.g., empower-personal-dashboard and broodminder-data), .github/workflows/publish.yml triggers on push to main. However, publishing is strictly gated:

• The prepare job extracts VERSION from pyproject.toml.
• If git tag v<version> exists (or PyPI already hosts <version>), the workflow skips building and publishing (should_publish=false).
• Consequently, when feature PRs merge without an explicit version bump (such as empower-personal-dashboard PR Compliance: missing-label-dependencies #46), the new capabilities remain unreleased under [Unreleased] in CHANGELOG.md until a separate version-bump commit is merged.

This creates operational friction:

1. Forgotten / Delayed Releases: Completed, reviewed, and fully tested features on main are not immediately consumable via pip install because developers/agents forget to bump version strings across multiple files (pyproject.toml, __version__, docs/openapi.yaml, CHANGELOG.md).
2. Version Synchronization Overhead: Manually updating version numbers across multiple contract files is error-prone and requires strict contract-test enforcement to prevent drift.
3. Workflow Drift Across Repos: Currently, empower-personal-dashboard and broodminder-data maintain nearly identical copy-pasted publish.yml workflows and scripts/pypi_onboard.py scripts with slight variations (e.g. check_pypi=True logic and differing action version pins).

Scope: Repositories Publishing Packages

This proposal specifically targets repositories that build, package, and publish libraries or CLI tools (e.g., PyPI packages, npm packages, container images), where main acts as the releasable source branch.

Release Strategy Options to Evaluate

1. Option A: Pure Continuous Delivery (Auto-SemVer on Every Merge to main)

   • Mechanism: Workflows inspect Conventional Commit messages since the last git tag (feat: → minor, fix: → patch, BREAKING CHANGE: → major). On merge, CI automatically increments the version, updates changelogs, commits/tags, and publishes.
   • Pros: True continuous delivery; zero forgotten releases; no manual version edits; immediate availability of bugfixes.
   • Cons: PyPI releases are immutable; small rapid PR merges cause version inflation and release churn; changelog quality may degrade if commit titles contain agent/bot review fixups.

2. Option B: Release PR Automation (Google Release-Please Pattern)

   • Mechanism: A background automation tracks merged commits on main and maintains a single open "Release PR" that aggregates pending changes, drafts the changelog, and increments the version. Maintainers merge the Release PR when ready to cut a release.
   • Pros: Full human/maintainer control over release timing; automated version calculation and changelog aggregation; clean separation between feature development and release milestones.
   • Cons: Additional bot PR in flight; requires managing PR limits and permissions.

3. Option C: Curated Batched Releases (Status Quo / Explicit Bump)

   • Mechanism: Feature PRs merge under [Unreleased] in CHANGELOG.md. Releases are deliberately cut via a dedicated chore(release): bump version to X.Y.Z PR.
   • Pros: High editorial control over changelog; batched release cohesion; prevents version inflation.
   • Cons: Release latency; human overhead; releases often stall waiting for someone to remember to bump the version.

Reusability Architecture: Central Vendoring vs. Per-Repo Implementation

An essential architectural question for the upcoming ADR is how this workflow is delivered across the fleet:

• Alternative 1: Central Reusable Workflow in petry-projects/.github (or .github/standards/workflows/)
  • Define a reusable workflow (e.g. pypi-publish-reusable.yml) or vendored workflow template consumed by package-publishing repos.
  • Keeps PyPI Trusted Publishing (OIDC), action version pins, twine validation, and tagging logic centralized.
  • Adheres to the org standard: "A decision-making reusable keeps its decision logic in a pure, tested script, with the workflow as thin I/O glue."
• Alternative 2: Per-Repo Custom Workflows
  • Each repo retains its own publish.yml and scripts/pypi_onboard.py.
  • Allows repo-specific packaging idiosyncrasies (e.g., OpenAPI spec validation, Beancount extensions, extra build hooks), but invites configuration drift and redundant maintenance.

Assessment

Dimension	Score	Rationale
Feasibility	High	Existing tools (python-semantic-release, release-please, or custom tested helper scripts) are mature and integrate cleanly with GitHub Actions.
Impact	High	Eliminates unreleased code stagnation across all package-publishing repos and unifies release mechanics across the org.
Urgency	Medium	Two active package repos (empower-personal-dashboard, broodminder-data) already experience friction and drift between their publish workflows.

Adversarial Review

Strongest objection: Python packages published to PyPI are immutable. Automatically releasing on every merge to main turns every minor commit into an irrevocable public artifact, creating version bloat and leaving no room for human editorial refinement of release notes or batching related features.

Rebuttal: The proposed ADR does not mandate naive commit-by-commit releasing. It explicitly evaluates Option B (Release PR automation via Release-Please) alongside Option A and Option C. Release-Please provides the best of both worlds: automated changelog generation and version calculation without publishing until maintainers merge the release PR. Furthermore, standardizing the publishing pipeline via .github eliminates the drift already occurring between empower-personal-dashboard and broodminder-data.

Goal & Next Steps

1. Perform and Register an ADR: Author an ADR in petry-projects/.github/standards/ establishing the org standard for package versioning, release triggers, and publishing workflows.
2. Decide Reusability Model: Determine whether package publication should be formalized as a shared reusable workflow in petry-projects/.github/standards/workflows/ or maintained as a template with pure tested decision logic.
3. Pilot: Implement the agreed strategy on empower-personal-dashboard and broodminder-data.

[don-petry]

@petry-projects/solution-architect - Review, analyze and advise.