git-a-grip 0.4.0__tar.gz

git_a_grip-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+# Check every push and PR; on a green main, cut the release tag.
+#
+# The release is CI's consequence, not its cause: nothing is bumped or tagged
+# until lint, tests, and the install proofs have passed on the merged commit.
+# Pushing the tag is what triggers publish.yml.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The floor in requires-python and whatever is current: the two
+        # versions where a syntax or stdlib assumption actually breaks.
+        python-version: ['3.11', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - run: uv sync
+
+      - name: Lint
+        run: uv run ruff check --config .ruff.toml src tests
+
+      - name: Format
+        run: uv run ruff format --check --config .ruff.toml src tests
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Build
+        run: uv build
+
+      # The commands must work from a bare wheel with no dev group and no
+      # `hooks` extra -- that is what `uv tool install git-a-grip` gets, and
+      # it is exactly what the dependency split could break.
+      - name: Commands run from the built wheel alone
+        run: |
+          uv run --isolated --no-project --with dist/*.whl \
+            pre-commit-audit --help
+          uv run --isolated --no-project --with dist/*.whl \
+            git-release --help
+
+      # The hooks are the other half of the split. try-repo builds them from
+      # .pre-commit-hooks.yaml in the isolated env a consumer would get, so
+      # this fails if ruff stops arriving via additional_dependencies -- which
+      # the repo's own config, using `language: system` locally, cannot catch.
+      - name: Hooks install and run as a consumer would get them
+        run: uv run --with pre-commit pre-commit try-repo . --all-files
+
+      - name: This repo's own config still passes
+        run: uv run --with pre-commit pre-commit run --all-files
+
+  bump:
+    needs: [check]
+    # Only a green push to main releases, and never the bump's own commit --
+    # that would recurse.
+    if: >-
+      github.event_name == 'push'
+      && github.ref == 'refs/heads/main'
+      && !startsWith(github.event.head_commit.message, 'bump:')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so commitizen can read the tags it bumps from, and a
+          # PAT because pushes made with the default GITHUB_TOKEN do not
+          # trigger workflows -- the tag would land and publish.yml would
+          # never fire.
+          fetch-depth: 0
+          token: ${{ secrets.BUMP_TOKEN }}
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version and tag
+        id: cz
+        run: |
+          PRE_SHA="$(git rev-parse HEAD)"
+          # --no-raise 21: "no commits eligible for a bump" is the normal
+          # outcome of a docs- or chore-only push, not a failure.
+          uv run cz --no-raise 21 bump --yes
+          POST_SHA="$(git rev-parse HEAD)"
+          if [[ "$PRE_SHA" == "$POST_SHA" ]]; then
+            echo "bumped=false" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "bumped=true" >>"$GITHUB_OUTPUT"
+
+          # cz bump rewrites the version in pyproject.toml only, so uv.lock's
+          # embedded git-a-grip version drifts. Re-lock and fold that into the
+          # bump commit, keeping the tag on the commit it names.
+          uv lock
+          if ! git diff --quiet -- uv.lock; then
+            TAG="$(git describe --tags --exact-match HEAD)"
+            git tag -d "$TAG"
+            git add uv.lock
+            git commit --amend --no-edit
+            git tag -a "$TAG" -m "$TAG"
+          fi
+
+      - name: Push bump commit and tag
+        if: steps.cz.outputs.bumped == 'true'
+        run: git push origin "HEAD:${{ github.ref_name }}" --tags

git_a_grip-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+# Publish to PyPI when ci.yml's bump job pushes a version tag.
+#
+# By the time a tag exists, CI has already passed on that commit -- the bump
+# job is gated on it -- so this workflow only builds and uploads.
+#
+# Authentication is PyPI trusted publishing (OIDC), so there is no API token
+# in this repo's secrets. It requires a one-time pending-publisher entry on
+# pypi.org naming this repo, this workflow file, and the `pypi` environment.
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      # The tag is the version. Publishing anything else would put a release
+      # on PyPI that no tag in this repo describes, and PyPI never lets that
+      # version number be reused.
+      - name: Tag matches the packaged version
+        run: |
+          packaged="v$(uv version --short)"
+          if [ "$packaged" != "${GITHUB_REF_NAME}" ]; then
+            echo "tag ${GITHUB_REF_NAME} != packaged ${packaged}" >&2
+            exit 1
+          fi
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # The OIDC token trusted publishing exchanges for an upload token.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

git_a_grip-0.4.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/

git_a_grip-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,58 @@
+default_install_hook_types: [pre-commit, commit-msg]
+default_stages: [pre-commit]
+
+repos:
+  # Dogfood: this repo's own hooks, run from the working tree rather than a
+  # pinned rev, so a change that breaks them fails here before it ships.
+  - repo: local
+    hooks:
+      - id: commitizen-early
+        name: Commitizen check (early)
+        entry: uv run commitizen-early
+        language: system
+        always_run: true
+        pass_filenames: false
+        fail_fast: true
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.17.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: mixed-line-ending
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff check
+        entry: uv run ruff-check-hook --config .ruff.toml
+        language: system
+        types: [python]
+        require_serial: true
+
+      - id: ruff-format
+        name: Ruff format
+        entry: uv run ruff-format-hook --config .ruff.toml
+        language: system
+        types: [python]
+        require_serial: true
+
+      - id: tests
+        name: Tests
+        entry: uv run pytest-hook tests/ -q
+        language: system
+        files: ^(src/|tests/).*
+        pass_filenames: false

git_a_grip-0.4.0/.pre-commit-hooks.yaml

@@ -0,0 +1,47 @@
+- id: commitizen-early
+  name: Commitizen check (early)
+  description: >-
+    Reject a non-conventional commit message during the pre-commit stage,
+    before the slow hooks run, by recovering it from git's argv.
+  entry: commitizen-early
+  language: python
+  stages: [pre-commit]
+  always_run: true
+  pass_filenames: false
+
+- id: ruff-check
+  name: Ruff check
+  description: >-
+    Lint with `ruff check --fix`, re-staging the files it fixed so the fix is
+    part of the commit rather than left dirty in the working tree.
+  entry: ruff-check-hook
+  language: python
+  types: [python]
+  # ruff is not a dependency of the package -- only these two hooks need it,
+  # and pulling it into `pip install git-a-grip` would tax the commands with
+  # a compiler-sized wheel they never call. Override the version per repo by
+  # setting your own `additional_dependencies: [ruff==x.y.z]`.
+  additional_dependencies: [ruff>=0.6]
+  # Both ruff hooks call `git add`; running them in parallel races index.lock.
+  require_serial: true
+
+- id: ruff-format
+  name: Ruff format
+  description: >-
+    Format with `ruff format`, re-staging the files it rewrote.
+  entry: ruff-format-hook
+  language: python
+  types: [python]
+  additional_dependencies: [ruff>=0.6]
+  require_serial: true
+
+- id: pytest
+  name: Tests
+  description: >-
+    Run the consuming repo's test suite from the repo root, through a runner
+    that resolves the project's own environment (`uv run pytest` by default,
+    override with `--runner=...`).
+  entry: pytest-hook
+  language: python
+  files: ^(src/|tests/).*
+  pass_filenames: false

git_a_grip-0.4.0/.ruff.toml

@@ -0,0 +1,67 @@
+line-length = 79
+show-fixes = true
+target-version = "py311"
+
+[lint]
+select = [
+  "A",  # https://beta.ruff.rs/docs/rules/#flake8-builtins-a
+  "ANN",  # https://beta.ruff.rs/docs/rules/#flake8-annotations-ann
+  "ARG",  # https://beta.ruff.rs/docs/rules/#flake8-unused-arguments-arg
+  "B",  # https://beta.ruff.rs/docs/rules/#flake8-bugbear-b
+  "C4",  # https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4
+  "COM",  # https://beta.ruff.rs/docs/rules/#flake8-commas-com
+  "C90",  # https://beta.ruff.rs/docs/rules/#mccabe-c90
+  "D200",  # One-line docstring should fit on one line
+  "D201",  # No blank lines allowed before function docstring
+  "D202",  # No blank lines allowed after function docstring
+  "D205",  # 1 blank line required between summary line and description
+  "D212",  # Multi-line docstring summary should start at the first line
+  "E",  # default! https://beta.ruff.rs/docs/rules/#error-e
+  "EM",  # https://beta.ruff.rs/docs/rules/#flake8-errmsg-em
+  "ERA",  # https://beta.ruff.rs/docs/rules/#eradicate-era
+  "EXE",  # https://beta.ruff.rs/docs/rules/#flake8-executable-exe
+  "F",  # default! https://beta.ruff.rs/docs/rules/#pyflakes-f
+  "FBT",  # https://beta.ruff.rs/docs/rules/#flake8-boolean-trap-fbt
+  "G",  # https://beta.ruff.rs/docs/rules/#flake8-logging-format-g
+  "I",  # https://beta.ruff.rs/docs/rules/#isort-i
+  "ICN",  # https://beta.ruff.rs/docs/rules/#flake8-import-conventions-icn
+  "ISC",  # https://beta.ruff.rs/docs/rules/#flake8-implicit-str-concat-isc
+  "N",  # https://beta.ruff.rs/docs/rules/#pep8-naming-n
+  "PGH",  # https://beta.ruff.rs/docs/rules/#pygrep-hooks-pgh
+  "PIE",  # https://beta.ruff.rs/docs/rules/#flake8-pie-pie
+  "PL",  # https://beta.ruff.rs/docs/rules/#pylint-pl
+  "PLE",  # https://beta.ruff.rs/docs/rules/#error-ple
+  "PLR",  # https://beta.ruff.rs/docs/rules/#refactor-plr
+  "PLW",  # https://beta.ruff.rs/docs/rules/#warning-plw
+  "PT",  # https://beta.ruff.rs/docs/rules/#flake8-pytest-style-pt
+  "PTH",  # https://beta.ruff.rs/docs/rules/#flake8-use-pathlib-pth
+  "PYI",  # https://beta.ruff.rs/docs/rules/#flake8-pyi-pyi
+  "Q",  # https://beta.ruff.rs/docs/rules/#flake8-quotes-q
+  "RET",  # https://beta.ruff.rs/docs/rules/#flake8-return-ret
+  "RSE",  # https://beta.ruff.rs/docs/rules/#flake8-raise-rse
+  "RUF",  # https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf
+  "S",  # https://beta.ruff.rs/docs/rules/#flake8-bandit-s
+  "SLF",  # https://beta.ruff.rs/docs/rules/#flake8-self-slf
+  "SIM",  # https://beta.ruff.rs/docs/rules/#flake8-simplify-sim
+  "TCH",  # https://beta.ruff.rs/docs/rules/#flake8-type-checking-tch
+  "TID",  # https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid
+  "TRY",  # https://beta.ruff.rs/docs/rules/#tryceratops-try
+  "W",  # https://beta.ruff.rs/docs/rules/#warning-w
+  "UP",  # https://beta.ruff.rs/docs/rules/#pyupgrade-up
+  "YTT",  # https://beta.ruff.rs/docs/rules/#flake8-2020-ytt
+]
+ignore = [
+  "S311",  # not using randomness for cryptography
+  "S101",  # assert is awesome
+  "I001",  # I do not care for its sorting choices
+  "S113",  # requests calls without timeouts are fine
+  "PLR0913",  # sometimes tests need 6+ fixtures
+  "PLC0415",  # deliberate lazy imports (CLI startup time, circular imports)
+]
+
+[lint.flake8-quotes]
+inline-quotes = "single"
+
+[format]
+quote-style = "single"
+docstring-code-format = true

git_a_grip-0.4.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+## v0.4.0 (2026-08-02)
+
+### Feat
+
+- prepare as a package for pypi, license, et al
+- add pre-commit-audit command to help keep local repos in line
+
+### Fix
+
+- have CI handle releases after successful checks, max automation
+
+## v0.3.1 (2026-08-02)
+
+### Fix
+
+- refuse to release on unrecognised arguments
+
+## v0.3.0 (2026-08-02)
+
+### Feat
+
+- remove bump-on-push in favour of the git-release command
+- git-release command that bumps before pushing
+
+## v0.2.0 (2026-08-02)
+
+### Feat
+
+- update wording, relase python hooks
+
+### Fix
+
+- skip hooks on the bump commit so pre-push cannot re-enter itself
+
+## v0.1.0 (2026-08-01)
+
+### Feat
+
+- commitizen-early and bump-on-push pre-commit hooks

git_a_grip-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Brown
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_a_grip-0.4.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: git-a-grip
+Version: 0.4.0
+Summary: Pre-commit hooks that fail fast on bad commit messages, re-stage what they fix, and run your tests -- plus a release command and a cross-repo hook audit.
+Project-URL: Homepage, https://github.com/dannybrown37/git-a-grip
+Project-URL: Source, https://github.com/dannybrown37/git-a-grip
+Project-URL: Issues, https://github.com/dannybrown37/git-a-grip/issues
+Project-URL: Changelog, https://github.com/dannybrown37/git-a-grip/blob/main/CHANGELOG.md
+Author-email: Danny Brown <dannybrown37@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: commitizen,git,hooks,pre-commit,ruff
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: commitizen>=4.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: hooks
+Requires-Dist: ruff>=0.6; extra == 'hooks'
+Description-Content-Type: text/markdown
+
+# git-a-grip
+
+Personal [pre-commit](https://pre-commit.com) hooks.
+
+```yaml
+repos:
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.3.1
+    hooks:
+      - id: commitizen-early
+      - id: ruff-check
+      - id: ruff-format
+      - id: pytest
+        args: [tests/, -q]
+```
+
+The commitizen and ruff hooks reach their tool through
+`sys.executable -m <tool>` inside the env pre-commit builds for this repo, so
+a consuming project needs no `cz` or `ruff` on PATH, no venv and no
+`uv`/`uvx` of its own. (`pytest` is the exception — see below.)
+
+Each hook pays only for what it uses: commitizen is a dependency of the
+package, while ruff is declared by the two ruff hooks themselves, through
+`additional_dependencies` in `.pre-commit-hooks.yaml`. You still pass
+nothing. Pin your own ruff by setting `additional_dependencies:
+[ruff==x.y.z]` on the hook.
+
+## `commitizen-early` (pre-commit stage)
+
+Rejects a non-conventional commit message in about a third of a second,
+instead of after the whole slow hook suite has run.
+
+Git runs `pre-commit` -> `prepare-commit-msg` -> editor -> `commit-msg` as
+separate invocations, so a `stages: [commit-msg]` commitizen hook can only
+ever fail *after* your tests. Nothing in `.pre-commit-config.yaml` reorders
+that. This hook instead recovers the message from the `git commit` process's
+own argv while the pre-commit stage is still running, and checks it first.
+
+Pair it with the upstream `commitizen` hook, which still catches the cases
+argv cannot reach (interactive editor, merge, rebase) — this one exits 0 and
+defers whenever it finds no message:
+
+```yaml
+  - repo: https://github.com/dannybrown37/git-a-grip
+    rev: v0.3.1
+    hooks:
+      - id: commitizen-early
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.17.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+```
+
+Put it first and give it `fail_fast: true` if you want it to short-circuit
+the rest of the stage.
+
+## `git-release` (command, not a hook)
+
+Bump, tag and push, in that order, exiting 0. For repos that release from a
+laptop rather than from CI. Give it an alias that says what it does — not
+`gp`, which reads as `git push` right up until it publishes something:
+
+```bash
+alias release='uvx --from git-a-grip git-release'
+```
+
+This repo itself no longer uses it: releases here are cut by CI once the
+checks on `main` pass (see below). The command remains for projects with no
+such pipeline, where the alternative is remembering the four commands by
+hand.
+
+On `main` it bumps and pushes; on any other branch it just pushes, so it can
+replace `git push` outright. Refuses to run against a dirty tree, and pushes
+anyway when there are no bumpable commits.
+
+This exists because a pre-push hook *cannot* do this cleanly. Git chooses
+which sha to push before hooks run, so a commit created afterwards leaves two
+options: cancel the push, or let git push the now-superseded sha and have it
+rejected as a non-fast-forward. Both end in `error: failed to push some refs`
+on top of a release that worked. Running as a command puts the bump before
+the push and the problem disappears.
+
+Configure what the bump rewrites via `[tool.commitizen]` in the consuming
+repo (`version_provider`, `version_files`).
+
+> A `bump-on-push` pre-push hook did this up to v0.2.1 and was removed in
+> v0.3.0 for the reason above. If you pin an older rev, that hook still
+> exists there; on upgrading, drop `- id: bump-on-push` and use this command.
+
+## `ruff-check` and `ruff-format` (pre-commit stage)
+
+`ruff check --fix` and `ruff format`, with the fixes **re-staged** so they are
+part of the commit you just made rather than a dirty working tree you have to
+`git add` and amend. Only the violations ruff could not fix stop the commit,
+via ruff's own exit code.
+
+Pass ruff's flags through `args`:
+
+```yaml
+      - id: ruff-check
+        args: [--config, .ruff.toml]
+```
+
+`--force-exclude` is always passed, so the `exclude` in your ruff config still
+applies to the paths pre-commit hands over explicitly. The re-staged set is
+narrowed by content digest — a file ruff did not change is never touched, and
+because pre-commit stashes unstaged changes while a hook runs, re-adding a
+file cannot sweep in an edit you deliberately left unstaged.
+
+The ruff version is this repo's pinned dependency. To hold a repo at a
+different one:
+
+```yaml
+      - id: ruff-format
+        additional_dependencies: [ruff==0.16.1]
+```
+
+## `pytest` (pre-commit stage)
+
+Runs the test suite from the repo root. This hook can't use the isolated env
+pre-commit builds here — a test suite needs the *consuming* project's
+dependencies — so it shells out to a runner that resolves that environment,
+`uv run pytest` by default. Everything else in `args` goes to pytest:
+
+```yaml
+      - id: pytest
+        args: [tests/, -q]
+
+      - id: pytest
+        args: ['--runner=uv run --extra api pytest', tests/, -q]
+```
+
+It runs from the repo root regardless of where git was invoked, and drops the
+`VIRTUAL_ENV`/`PYTHONPATH` that pre-commit exports for its own hook env —
+which would otherwise point the runner at an environment holding none of your
+project's dependencies. Narrow when it runs with `files:` (default
+`^(src/|tests/).*`).
+
+## `pre-commit-audit` (command, not a hook)
+
+Audit every local repo's pre-commit setup at once, so a hook that drifted or
+never got installed shows up as a line rather than a surprise:
+
+```bash
+uvx --from git-a-grip pre-commit-audit
+```
+
+It walks the given trees (default: this repo's sibling directories), stops at
+each git working tree, and reports four things: which of this repo's hooks
+each project uses and the `rev` it pins, third-party hooks grouped by source
+repo and rev, one-off `repo: local` hooks with their entry, and repos with no
+usable config at all. `--json` emits the same data unformatted.
+
+```bash
+pre-commit-audit ~/projects ~/work
+pre-commit-audit --json | jq '.[] | select(.hooks == [])'
+```
+
+## Installing the commands
+
+The hooks need no installation — pre-commit builds this repo an isolated env
+from the `rev` you pin. The two commands (`git-release`, `pre-commit-audit`)
+are ordinary console scripts, published to PyPI:
+
+```bash
+uvx --from git-a-grip pre-commit-audit    # one-off
+uv tool install git-a-grip                # both commands, on PATH
+```
+
+That install carries only what the commands import — commitizen and pyyaml —
+not the ruff the hooks use. To run the hook entry points by hand as well, ask
+for the extra:
+
+```bash
+uv tool install 'git-a-grip[hooks]'
+```
+
+Straight from a tag works too, and is the way to run something not yet
+released:
+
+```bash
+uvx --from git+https://github.com/dannybrown37/git-a-grip@v0.3.1 git-release
+```
+
+## Releasing
+
+Merge to `main`. That is the whole gesture.
+
+`ci.yml` runs lint, tests and the install proofs on the merged commit; only
+if they all pass does its `bump` job run `cz bump`, which writes the version
+and changelog, commits, and tags. Pushing that tag triggers `publish.yml`,
+which builds and uploads to PyPI via trusted publishing. A push with no
+bumpable commits (docs, chores) ends after the checks and releases nothing.
+
+Nothing is tagged before the checks pass, so a red build cannot leave a
+version number stranded on a release that never shipped.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+This repo eats its own dog food: both hooks are wired into its own
+`.pre-commit-config.yaml`.