Opinionated blueprint for Python packages with automated CI, releases, and publishing.

merge to main  →  release-please opens version bump PR
                   (auto-generated CHANGELOG.md + version bump)

Review the PR. To customize the changelog before releasing, push edits to the release-please branch:

git fetch origin
git checkout release-please--branches--main
# edit CHANGELOG.md
git add CHANGELOG.md
git commit -m "docs: refine changelog for vX.Y.Z"
git push

Then merge the PR:

merge release PR  →  git tag + GitHub Release → PyPI publish → RTD rebuild

Note: release-please regenerates the PR when new commits land on main. Edit the changelog only when you're ready to merge, and don't push to main in between.

git tag v1.0.0-rc.1
git push origin v1.0.0-rc.1
# → PyPI publish + GitHub Release (marked as pre-release)

Needed so release-please PRs trigger CI (the default GITHUB_TOKEN can't).

1. Create a GitHub App with Contents and Pull requests read & write
2. Install it on your repo
3. Add secrets APP_ID and APP_PRIVATE_KEY

1. Create a pypi environment in repo settings (Settings → Environments)
2. Add a trusted publisher — workflow: publish.yaml, environment: pypi

Connect your repo at readthedocs.org. Rebuilds automatically on push.

Add CODECOV_TOKEN as a repository secret.

Add CI Success as a required status check on main.

Warning: GitHub matches required checks by exact job name string. If you rename a job in a workflow, update branch protection to match — otherwise the old check silently never completes.