Maintain prodockit¶

This section is for maintainers of the prodockit repository. It covers the package's own source, test matrix, documentation artifacts, pinned build inputs, GitHub Actions workflows, PyPI release, and public documentation deployment.

If you are writing and publishing a document with prodockit, use Publish a document instead. Machine setup, prodockit-template, template syncing, PDF generation, and Pages publication belong to that author workflow.

The maintenance cycle¶

The maintenance cycle below keeps repository identity, dependency versions, generated artifacts, and release automation under review.

1. Start from a clean default branch

   Update the branch GitHub publishes and confirm that no local work will be mixed into the maintenance change:

   git switch main
   git pull --ff-only
   git status --short
   

   Create a branch for the work rather than maintaining directly on main:

   git switch -c maintenance/update-build-inputs
   

2. Check repository identity

   Confirm that the website links, edit buttons, brand icon, and README badges still describe the remote this checkout uses:

   prodockit sync-repo --check
   

   If it reports drift, run prodockit sync-repo, review the diff, and repeat the check. See Repository metadata.

3. Check pinned build inputs

   First check that every file agrees without asking the network for newer releases:

   prodockit pins --check --offline
   

   Use the scheduled drift workflow to decide whether to adopt a newer release. Do not upgrade merely to clear a notification: rebuild and compare the output first. See Version pinning and drift.

4. Build the deliverables locally

   Build in the same order as GitHub Actions. The PDF comes first because zensical build copies it into the published site:

   prodockit pdf
   zensical build --clean --strict
   

   Then run the checks appropriate to the repository. For prodockit itself:

   ruff check .
   mypy src
   prodockit pins --check --offline
   pytest
   

5. Review, push, and use the pull request gates

   Review both source and generated output. Commit the source changes, push the branch, and open a pull request:

   git diff --check
   git status --short
   git add <reviewed-files>
   git commit -m "Maintain project build inputs"
   git push -u origin HEAD
   gh pr create
   

   GitHub Actions runs the test matrix and strict documentation build on the pull request. Merge only after those required checks pass. Package releases have additional gates described in Build and release.

Choose the right maintenance tool¶

What automation does—and does not—prove¶

The workflows deliberately divide responsibility:

A green workflow proves the question in its own row, not every row. In particular, a passing pull request does not publish PyPI, and a successful Pages deployment does not by itself prove the public URL serves the new bytes. The deployment workflow performs that final delivery check separately.

Suggested cadence¶

The command-line map inventories the public CLI that a maintainer must keep consistent. The pages after it explain each repository maintenance job in depth.