Publish foreman on PyPi Registry

[n1arash]

Summary

Foreman is currently distributed only from source. Publish it to the PyPI (https://pypi.org/) registry as foreman-orchestrator so users can pip install foreman-orchestrator (or uv tool
install foreman-orchestrator) instead of cloning the repo. This issue tracks the full release automation: a versioning rule, a publish pipeline, dependency automation, auto-publish on
version bump, and live status/coverage badges.

Motivation

• One-command install (pip / uv / pipx) lowers the barrier to trying Foreman.
• Tagged, reproducible releases instead of "install from main."
• Trusted, automated publishing removes manual twine upload steps and long-lived API tokens.

Scope

1. Versioning rule

• Adopt Semantic Versioning (https://semver.org/) (MAJOR.MINOR.PATCH) as the project rule, documented in CONTRIBUTING.md / CHANGELOG.md.
• Single source of truth for the version — keep pyproject.toml version authoritative (or move to hatch-vcs / git-tag-derived versioning) so the README badge, changelog, and package
  metadata never drift.
• Define the bump policy: breaking pipeline/CLI changes → MAJOR, new features → MINOR, fixes → PATCH. Pre-1.0 caveats noted.
• Every release entry recorded in CHANGELOG.md (Keep a Changelog format).

2. Publish CI/CD

• Add .github/workflows/ (none exist today) with a build + publish workflow.
• Build sdist + wheel with hatchling, validate with twine check, and publish via PyPI Trusted Publishing (OIDC) (https://docs.pypi.org/trusted-publishers/) — no stored API token.
• Publish to TestPyPI first (on pre-release tags or manual workflow_dispatch) to verify the package before hitting prod PyPI.
• Gate publish on the test suite passing.

3. Dependabot

• Add .github/dependabot.yml to keep dependencies current:
  • pip ecosystem for pyproject.toml (runtime + dev extras).
  • github-actions ecosystem to keep workflow action versions pinned and updated.
• Weekly schedule, grouped minor/patch PRs to reduce noise.

4. Auto-publish on version bump

• Trigger the publish workflow automatically when the version changes.
• Two acceptable mechanisms (pick one):
  • Tag-driven: pushing a vX.Y.Z git tag builds and publishes; CI asserts the tag matches pyproject.toml.
  • Bump-driven: a merge to main that changes version in pyproject.toml creates the tag + GitHub Release, then publishes.
• Create a GitHub Release with auto-generated notes from the changelog as part of the same flow.

5. Test badges + coverage badges

• Wire Codecov (https://about.codecov.io/) (or Coveralls) into CI; upload coverage from the pytest run.
• Replace/augment the current static README badges with live ones:
  • CI / test-suite status (GitHub Actions workflow badge).
  • Coverage % (Codecov badge).
  • PyPI version + Python versions + monthly downloads (img.shields.io/pypi/...).

Acceptance criteria

• pip install foreman-orchestrator works from PyPI and foreman CLI launches.
• Versioning rule (SemVer) documented with a single source of truth.
• Publish workflow uses Trusted Publishing (no API token secrets), gated on green tests, with a TestPyPI dry-run path.
• dependabot.yml covers pip + github-actions.
• A version bump / tag automatically publishes the release and creates a GitHub Release.
• README shows live CI status, coverage, and PyPI badges.

[ehsantg]

All acceptance criteria are met — closing.

---

✅ Acceptance criteria

• pip install foreman-orchestrator works — v0.6.0 is live on PyPI and the foreman CLI entry-point is registered.
• Versioning rule documented — CONTRIBUTING.md defines SemVer MAJOR/MINOR/PATCH bump policy; pyproject.toml is the single source of truth for the version.
• Trusted Publishing (OIDC), gated on tests, TestPyPI dry-run — .github/workflows/publish.yml uses pypa/gh-action-pypi-publish with id-token: write; publish is blocked until the test job passes; pre-release tags (vX.Y.ZaN/bN/rcN) go to TestPyPI, stable tags go to PyPI.
• dependabot.yml covers pip + github-actions — .github/dependabot.yml with weekly grouped minor/patch updates for both ecosystems.
• Tag auto-publishes + creates GitHub Release — pushing v0.6.0 triggered the workflow, published to PyPI, and created the v0.6.0 GitHub Release with auto-generated notes.
• Live badges in README — CI status, Codecov coverage, PyPI version, Python versions, and monthly downloads badges all wired up.

What was shipped (PR #19)

File	Purpose
.github/workflows/ci.yml	Test matrix (Python 3.11/3.12/3.13) + Codecov upload
.github/workflows/publish.yml	Build → twine check → TestPyPI / PyPI via OIDC → GitHub Release
.github/dependabot.yml	Weekly grouped pip + actions updates
CONTRIBUTING.md	SemVer bump policy + release process
CHANGELOG.md	Reformatted to Keep a Changelog with dates and comparison links for all 21 versions
pyproject.toml	Author, classifiers (3.11/3.12/3.13), project URLs, pytest-cov dev dep
README.md	Static badges → live CI / coverage / PyPI badges