Merge pull request #48 from nm-packages/codex/release-work

Improve contributor workflow, tooling, and release guidance

Author: nickmoreton

.github/workflows/test.yml

@@ -11,7 +11,38 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  test-sqlite:
+  test-sqlite-release:
+    if: github.base_ref == 'release'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - python: "3.10"
+            toxenv: py310-django42-wagtail63-sqlite
+          - python: "3.14"
+            toxenv: py314-django52-wagtail72-sqlite
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+
+      - name: Sync dependencies
+        id: sync-dependencies
+        run: uv sync --locked
+
+      - name: Test with tox
+        id: test-with-tox
+        run: uv run tox -e ${{ matrix.toxenv }}
+
+  test-sqlite-main:
+    if: github.base_ref == 'main'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -22,26 +53,25 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v3
 
-      - name: Set up Python
-        id: setup-python
-        uses: actions/setup-python@v4
+      - name: Set up uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           python-version: ${{ matrix.python }}
+          enable-cache: true
 
-      - name: Install dependencies
-        id: install-dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox tox-gh-actions
+      - name: Sync dependencies
+        id: sync-dependencies
+        run: uv sync --locked
 
       - name: Test with tox
         id: test-with-tox
-        run: |
-          tox
+        run: uv run tox
         env:
           DATABASE: ${{ matrix.database }}
 
   test-postgres:
+    if: github.base_ref == 'main'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -63,22 +93,20 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v3
 
-      - name: Set up Python
-        id: setup-python
-        uses: actions/setup-python@v4
+      - name: Set up uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           python-version: ${{ matrix.python }}
+          enable-cache: true
 
-      - name: Install dependencies
-        id: install-dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox tox-gh-actions
+      - name: Sync dependencies
+        id: sync-dependencies
+        run: uv sync --locked
 
       - name: Test with tox
         id: test-with-tox
-        run: |
-          tox
+        run: uv run tox
         env:
           DB_NAME: postgres
           DB_USER: postgres
@@ -89,6 +117,7 @@ jobs:
 
 
   test-mysql:
+    if: github.base_ref == 'main'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -112,22 +141,20 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v3
 
-      - name: Set up Python
-        id: setup-python
-        uses: actions/setup-python@v4
+      - name: Set up uv
+        id: setup-uv
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           python-version: ${{ matrix.python }}
+          enable-cache: true
 
-      - name: Install dependencies
-        id: install-dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install tox tox-gh-actions
+      - name: Sync dependencies
+        id: sync-dependencies
+        run: uv sync --locked
 
       - name: Test with tox
         id: test-with-tox
-        run: |
-          tox
+        run: uv run tox
         env:
           DB_NAME: mysql
           DB_USER: root

.pre-commit-config.yaml

@@ -1,16 +1,14 @@
 repos:
-  - repo: https://github.com/pycqa/isort
-    rev: 7.0.0
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.11.3
     hooks:
-      - id: isort
-  - repo: https://github.com/psf/black
-    rev: 25.11.0
+      - id: uv-lock
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.11
     hooks:
-      - id: black
-  - repo: https://github.com/pycqa/flake8
-    rev: 7.3.0
-    hooks:
-      - id: flake8
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
   - repo: https://github.com/jackdewinter/pymarkdown
     rev: v0.9.33
     hooks:
@@ -19,12 +17,8 @@ repos:
           - --disable-rules
           - line-length
           - scan
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.21.1
-    hooks:
-    -   id: pyupgrade
   - repo: https://github.com/adamchainz/django-upgrade
     rev: "1.29.1"  # replace with latest tag on GitHub
     hooks:
-    -   id: django-upgrade
-        args: [--target-version, "5.2"]   # Replace with Django version
+      - id: django-upgrade
+        args: [--target-version, "5.2"]   # Replace with Django version

.python-version

@@ -0,0 +1 @@
+3.12

AGENTS.md

@@ -0,0 +1,79 @@
+# Agent Conventions
+
+## Purpose
+
+This file guides coding agents working in this repository. Keep it operational and project-specific. Use `README.md` for package usage and `docs/developer.md` for local setup details; do not duplicate those walkthroughs here.
+
+## Workflow Tools
+
+- Use `uv` for contributor and agent workflows by default.
+- Use `uv sync` to create or refresh the local environment.
+- Use `uv run ...` for project commands instead of bare `python`, `pip`, or globally installed tooling unless the task explicitly requires it.
+- Use Ruff for Python formatting and linting by default.
+
+## Repo Map
+
+- `wagtail_honeypot/`: package behavior and public implementation.
+- `wagtail_honeypot/models.py`: honeypot settings defaults and form submission logic.
+- `wagtail_honeypot/templatetags/honeypot_tags.py`: template tag context and field names.
+- `wagtail_honeypot/templates/` and `wagtail_honeypot/static/`: rendered markup and browser-side behavior.
+- `wagtail_honeypot/locale/`: translations.
+- `tests/`: unit coverage for models, methods, forms, and template tags.
+- `tests/testapp/`: minimal Wagtail integration site; use it only when a change needs page-level or form-flow coverage.
+
+## Change Conventions
+
+- Put reusable package behavior in `wagtail_honeypot/`, not in `tests/testapp/`.
+- Change `models.py` when adjusting honeypot defaults, settings handling, or form submission decisions.
+- Change `templatetags/honeypot_tags.py` and `templates/tags/honeypot_fields.html` when adjusting rendered field names, context, or markup.
+- Change `static/css/` or `static/js/` only for browser behavior related to hiding or presenting honeypot fields.
+- Update `locale/` only when user-facing strings change.
+- Keep `tests/testapp/` focused on integration behavior; do not treat it as a second implementation surface.
+
+## Compatibility Rules
+
+- Preserve existing `HONEYPOT_*` setting names and behavior unless the task explicitly changes support policy.
+- Avoid unnecessary breaking changes to template tag output, rendered field attributes, or form-processing semantics.
+- Treat the Django and Wagtail support matrix in `tox.ini` as a constraint when making changes.
+- Preserve backwards compatibility across supported versions unless the task explicitly requires otherwise.
+
+## Testing Expectations
+
+- For model or method changes, add or update focused tests in `tests/test_models.py` or `tests/test_methods.py`.
+- For form submission behavior, update `tests/test_form.py` and verify both accepted and ignored submissions.
+- For template tag or rendered field changes, update `tests/test_tags.py` with context and rendered HTML assertions.
+- Use `tests/testapp/` coverage when the change affects Wagtail page behavior or end-to-end form flow.
+- For translation or configuration changes, add focused assertions where practical.
+- Run `make lint` or `uv run ruff check .` for Python style checks.
+- Run `make format` or `uv run ruff format .` when updating Python formatting.
+- Run `make test` or `uv run coverage run manage.py test` for the default suite.
+- Use `make tox` or `uv run tox --skip-missing-interpreters` only when matrix coverage is relevant to the task.
+
+## Documentation Rules
+
+- Update `README.md` when package usage, settings, or integration steps change for users.
+- Update `docs/developer.md` when local development workflow changes.
+- Update `CHANGELOG` under `## Unreleased` for every PR. Keep entries short, flat, and user or contributor facing.
+- Keep `AGENTS.md` concise and directive; do not turn it into a duplicate contributor guide.
+
+## PR Readiness
+
+- Keep the pull request title and body aligned with the current branch scope.
+- Update the PR title whenever the branch scope changes materially and the current title no longer describes the work accurately.
+- Update the PR description whenever behavior, tooling, documentation, or test coverage changes materially from the current summary.
+- The maintained PR body should cover the behavior change, docs or tooling updates, and verification performed.
+- When handling pull request review suggestions that require code changes, commit the fix, push the branch, and update the review reply after the branch reflects the final change set.
+- Treat the PR title, PR summary, and `CHANGELOG` entry as required closing steps before the branch is ready.
+
+## Branch Workflow
+
+- Treat `release` as the repository default branch.
+- Start all new work from `release`; it tracks the latest changes that are not yet released to PyPI.
+- Treat `main` as the release-preparation branch, not the starting point for routine feature or fix work.
+- Target merge requests at `release`.
+
+## Change Boundaries
+
+- Do not change version metadata, supported-version claims, or migrations unless the task requires it.
+- Keep commit scope narrow and tied to one behavior change.
+- Prefer minimal edits that preserve the package's existing API and documented behavior.

CHANGELOG

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+- Document the `release` branch workflow and require merge requests to target `release`
+- Add agent instructions to keep pull request titles and summaries current and update the changelog on every PR
+- Require review-driven code changes to be committed, pushed, and followed by an updated review reply
+- Adopt `uv` as the default contributor workflow and lock the local development environment
+- Run a reduced SQLite tox subset for `release` pull requests while keeping the full matrix for `main`
+- Replace Black, isort, Flake8, and pyupgrade with Ruff for Python formatting and linting
+- Add Makefile help output plus dedicated `lint` and `format` targets
+- Update contributor and agent documentation for the new development workflow
+- Update the honeypot field documentation for the `aria-hidden="true"` accessibility attribute
+- Sync the Ruff pre-commit hook version with the locked Ruff release and correct the developer doc Wagtail baseline
+
 ## [1.2.1] - 2026-02-05
 
 - Add locale support

Makefile

@@ -1,17 +1,44 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help sync lint format run mail test tox migrate superuser
+
+help:
+	@printf "Available targets:\n"
+	@printf "  make sync        Sync the uv-managed development environment\n"
+	@printf "  make lint        Run Ruff lint checks\n"
+	@printf "  make format      Run Ruff fixes and formatting\n"
+	@printf "  make run         Start the local Django development server\n"
+	@printf "  make mail        Start Mailhog for local email testing\n"
+	@printf "  make test        Run the default Django test suite with coverage\n"
+	@printf "  make tox         Run the supported compatibility matrix\n"
+	@printf "  make migrate     Apply local database migrations\n"
+	@printf "  make superuser   Create the default local admin user\n"
+
+sync:
+	uv sync
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff check . --fix
+	uv run ruff format .
+
 run:
-	python manage.py runserver 0:8000
+	uv run python manage.py runserver 0:8000
 
 mail:
 	docker run -p 8025:8025 -p 1025:1025 mailhog/mailhog
 
 test:
-	coverage run manage.py test && coverage report
+	uv run coverage run manage.py test
+	uv run coverage report
 
 tox:
-	tox --skip-missing-interpreters
+	uv run tox --skip-missing-interpreters
 
 migrate:
-	python manage.py migrate
+	uv run python manage.py migrate
 
 superuser:
-	@echo "from django.contrib.auth import get_user_model; get_user_model().objects.create_superuser('admin', 'admin@admin.com', 'changeme')" | python manage.py shell
+	@echo "from django.contrib.auth import get_user_model; get_user_model().objects.create_superuser('admin', 'admin@admin.com', 'changeme')" | uv run python manage.py shell

README.md

@@ -162,7 +162,7 @@ the field could be seen for a flash while the page loads -->
 
 The field should be visibly hidden and not be available to receive any value from a site visitor.
 
-> When rendered, the fields will have the HTML attributes `tabindex="-1" autocomplete="off"` to prevent a site visitor from using the tab key to move to the field and disable any autocomplete browser functions.
+> When rendered, the fields will have the HTML attributes `tabindex="-1" autocomplete="off" aria-hidden="true"` to keep them out of normal keyboard navigation, disable browser autocomplete, and hide them from assistive technology.
 
 ## Developer Documentation