Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 0 additions & 18 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,8 @@

<!-- What does this PR change and why? -->

## Related Issues

<!-- e.g. Closes #123 -->

## Type of Change

<!--
Add a release label to this PR from the Labels section of the PR sidebar
(not a prefix in the PR title or commit message). It sets the release notes section and the version bump:
breaking -> major
feature / enhancement -> minor
bug / fix -> patch
chore / ci / dependencies / documentation / refactor -> patch
skip-changelog -> excluded from release notes
-->

## Checklist

- [ ] `just lint` passes
- [ ] `just test` passes
- [ ] Tests added or updated for the change
- [ ] `README.md` updated if needed
- [ ] Release label added
25 changes: 18 additions & 7 deletions copier.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,16 @@ _exclude:
- "__pycache__"
- ".git"
- ".DS_Store"
# Example code is only added on `copier copy`; `copier update` never adds it back
# Example code is only added on `copier copy`; `copier update` never adds it back.
# Docs and release files are also skipped when their option is off
- "{% if _copier_operation == 'update' %}src/*/hello_world.py{% endif %}"
- "{% if _copier_operation == 'update' %}tests/test_hello_world.py{% endif %}"
- "{% if _copier_operation == 'update' %}scripts/sync-labels.sh{% endif %}"
- "{% if _copier_operation == 'update' %}/docs{% endif %}"
- "{% if _copier_operation == 'update' %}zensical.toml{% endif %}"
- "{% if _copier_operation == 'update' %}.github/release-drafter.yml{% endif %}"
- "{% if _copier_operation == 'update' %}.github/workflows/release-drafter.yml{% endif %}"
- "{% if _copier_operation == 'update' %}.github/workflows/release.yml{% endif %}"
- "{% if _copier_operation == 'update' or not use_releases %}scripts/sync-labels.sh{% endif %}"
- "{% if _copier_operation == 'update' or not use_docs %}/docs{% endif %}"
- "{% if _copier_operation == 'update' or not use_docs %}zensical.toml{% endif %}"
- "{% if _copier_operation == 'update' or not use_releases %}.github/release-drafter.yml{% endif %}"
- "{% if _copier_operation == 'update' or not use_releases %}.github/workflows/release-drafter.yml{% endif %}"
- "{% if _copier_operation == 'update' or not use_releases %}.github/workflows/release.yml{% endif %}"
_tasks:
- uv lock

Expand All @@ -43,3 +44,13 @@ github_repo:
type: str
help: GitHub owner/repo (used for the README badges)
validator: "{% if github_repo.count('/') != 1 %}Use the owner/repo format{% endif %}"

use_docs:
type: bool
help: Include Zensical docs (docs/, zensical.toml, docs build in CI and hooks)?
default: false

use_releases:
type: bool
help: Include Release Drafter, the manual release workflow, and release labels?
default: false
2 changes: 2 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ render:
uvx copier copy --trust --defaults --vcs-ref HEAD \
--data project_name=demo-project \
--data github_repo=example-owner/demo-project \
--data use_docs=true \
--data use_releases=true \
. {{ rendered }}
# Install Homebrew tools from the Brewfile
setup:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
## Related Issues

<!-- e.g. Closes #123 -->
{%- if use_releases %}

## Type of Change

Expand All @@ -17,11 +18,14 @@ Add a release label to this PR from the Labels section of the PR sidebar
chore / ci / dependencies / documentation / refactor -> patch
skip-changelog -> excluded from release notes
-->
{%- endif %}

## Checklist

- [ ] `just lint` passes
- [ ] `just test` passes
- [ ] Tests added or updated for the change
- [ ] `README.md` updated if needed
{%- if use_releases %}
- [ ] Release label added
{%- endif %}
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
{% raw -%}
name: Python CI Checks

on:
Expand Down Expand Up @@ -32,9 +33,11 @@ jobs:
- name: Unit tests
run: |
just test
{%- endraw %}{% if use_docs %}{% raw %}
- name: Docs build
run: |
just docs-build
{%- endraw %}{% endif %}{% raw %}
markdownlint:
runs-on: ubuntu-slim
permissions:
Expand All @@ -48,3 +51,4 @@ jobs:
uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24.2.0
with:
globs: "**/*.md"
{%- endraw %}
2 changes: 2 additions & 0 deletions template/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,8 @@ dmypy.json

# Claude
.claude/*.local.*
Claude.md.example
CLAUDE.md

# Dev Container
.devcontainer/devcontainer-lock.json
14 changes: 10 additions & 4 deletions template/CLAUDE.md.example.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,16 @@ Uses `uv` for environment/dependency management and `just` as the command runner
- `just test` - run pytest with coverage (fails under 98%)
- `just audit` - check dependencies for known vulnerabilities (pip-audit)
- `just markdownlint` - lint Markdown files (markdownlint-cli2, config in `.markdownlint-cli2.jsonc`)
{%- if use_docs %}
- `just docs-build` - build the docs with Zensical in strict mode (`zensical.toml`, pages in `docs/`)
- `just docs-serve` - serve the docs locally with live reload
{%- endif %}
- `just zizmor` - audit GitHub Actions workflows for security issues
- `just git-leaks` - scan staged changes for secrets
{%- if use_releases %}
- `just set-github-labels` - remove non-release default labels, then create/update the release labels on GitHub
(`scripts/sync-labels.sh`, needs `gh`, for fresh repos)
{%- endif %}
- `uv add <pkg>` / `uv add --dev <pkg>` - add a runtime / dev dependency (never edit `uv.lock` by hand)
- `uv run {{ project_name }}` - run the app entry point

Expand All @@ -31,10 +35,10 @@ Run `just lint` and `just test` before considering a change done.
- `src/{{ package_name }}/__init__.py` - `main()` entry point, exposed as the `{{ project_name }}` script
- `tests/` - pytest tests; import the package as `from {{ package_name }}.<module> import ...`
- `prek.toml` - git hook config (`prek install` to enable)
- `.github/workflows/` - `python.yml` (lint, tests, docs build, markdownlint),
`security.yml` (zizmor, gitleaks, pip-audit),
- `.github/workflows/` - `python.yml` (lint, tests,{% if use_docs %} docs build,{% endif %} markdownlint),
`security.yml` (zizmor, gitleaks, pip-audit){% if use_releases %},
`release-drafter.yml` (draft release, PR labels), `release.yml` (manual release)
- `.github/release-drafter.yml` - release label → version bump / release notes section mapping
- `.github/release-drafter.yml` - release label → version bump / release notes section mapping{% endif %}
- `.github/dependabot.yml` - weekly updates for actions, uv, dev container image and features
- `.devcontainer/` - dev container; base image, `just`, and `uv` pinned by tag + digest
- `scripts/` - repo maintenance scripts
Expand All @@ -46,7 +50,7 @@ Run `just lint` and `just test` before considering a change done.
- Type hints on public functions; code must pass `ty check`
- Renaming the project means updating `[project] name`, the `src/<name>/` folder, and `[project.scripts]` together

## CI, security, and releases
## CI{% if use_releases %}, security, and releases{% else %} and security{% endif %}

- Pin GitHub Actions to a full commit SHA with a version comment (`uses: owner/action@<sha> # vX.Y.Z`);
run `just zizmor` after editing workflows
Expand All @@ -56,6 +60,8 @@ Run `just lint` and `just test` before considering a change done.
- uv is pinned to 0.13.x in four places that must stay in sync: `[tool.uv] required-version` and the
`uv_build` requirement in `pyproject.toml`, `setup-uv` `version` in the workflows, and the uv image in
`.devcontainer/Dockerfile`
{%- if use_releases %}
- Do not bump `[project] version` by hand; the Release workflow does it
- Every PR needs a release label (GitHub PR label, not a title/commit prefix): `breaking`, `feature`,
`enhancement`, `bug`, `fix`, `chore`, `ci`, `dependencies`, `documentation`, `refactor`, or `skip-changelog`
{%- endif %}
12 changes: 12 additions & 0 deletions template/README.md.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -34,28 +34,39 @@ manage project configuration and commands
* `just test` - run unit tests
* `just audit` - check dependencies for known vulnerabilities with pip-audit
* `just markdownlint` - lint Markdown files with markdownlint-cli2
{%- if use_docs %}
* `just docs-build` - build the docs site with Zensical (strict mode, output in `site/`)
* `just docs-serve` - serve the docs locally with live reload
{%- endif %}
* `just prek` - run pre-commit hooks via prek
* `just git-leaks` - scan staged changes for secrets with gitleaks
* `just zizmor` - audit GitHub Actions workflows for security issues
{%- if use_releases %}
* `just set-github-labels` - remove GitHub's non-release default labels, then create or update the release labels
(for fresh repos, requires `gh auth login`)
{%- endif %}
* `uv add {package}` - install a dependency

## CI and Security

| Workflow | Runs on | Purpose |
| --------------------- | ----------------------- | -------------------------------------------- |
{%- if use_docs %}
| `python.yml` | push / PR to `main` | lint, unit tests, docs build, markdownlint |
{%- else %}
| `python.yml` | push / PR to `main` | lint, unit tests, markdownlint |
{%- endif %}
| `security.yml` | push to `main`, all PRs | zizmor, gitleaks, pip-audit dependency audit |
{%- if use_releases %}
| `release-drafter.yml` | push to `main`, PRs | update the draft release, label PRs |
| `release.yml` | manual | publish a release |
{%- endif %}

* GitHub Actions are pinned to full commit SHAs, with the version in a trailing comment
* Dependabot (`.github/dependabot.yml`) checks monthly for updates to GitHub Actions, Python
dependencies, the dev container image, and dev container features. New releases wait 7 days
before an update is proposed. Dependabot PRs get the `dependencies` label
{%- if use_releases %}

## Releases

Expand Down Expand Up @@ -83,6 +94,7 @@ labels; any other repository labels you add are ignored.
* Merging to `main` updates a draft GitHub Release with the next version and notes
* To release, run the **Release** workflow from the Actions tab. It bumps the version in
`pyproject.toml`/`uv.lock`, tags the release, and uploads build artifacts. Release notes live on the GitHub Release
{%- endif %}

## Usage

Expand Down
4 changes: 4 additions & 0 deletions template/justfile → template/justfile.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,14 @@ ci-lint:
uv run ruff format --check .
uv run codespell
uv run actionlint .github/workflows/*.yml
{%- if use_docs %}
# Build the docs in strict mode (output in site/)
docs-build:
uv run zensical build --strict
# Serve the docs locally with live reload
docs-serve:
uv run zensical serve
{%- endif %}
# Scan staged changes for secrets
git-leaks:
gitleaks git --pre-commit --staged --redact
Expand All @@ -34,9 +36,11 @@ markdownlint:
# Run the git hooks on staged files
prek:
uv run prek
{%- if use_releases %}
# Remove non-release default labels and sync the release labels on GitHub
set-github-labels:
./scripts/sync-labels.sh
{%- endif %}
# Install Homebrew tools and sync the project
setup:
brew bundle install
Expand Down
2 changes: 2 additions & 0 deletions template/prek.toml → template/prek.toml.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ hooks = [
entry = "just test",
pass_filenames = false
},
{%- if use_docs %}
{
id = "docs-build",
name = "docs build",
Expand All @@ -40,6 +41,7 @@ hooks = [
files = "^(docs/|src/|zensical\\.toml$)",
pass_filenames = false
},
{%- endif %}
{
id = "markdownlint",
name = "markdownlint",
Expand Down
2 changes: 2 additions & 0 deletions template/pyproject.toml.jinja
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,15 @@ dev = [
"ruff>=0.17.3",
"ty>=0.0.96",
]
{%- if use_docs %}
docs = [
"mkdocstrings[python]>=1.0.8",
"zensical>=0.1.0",
]

[tool.codespell]
skip = "./site" # Built docs output
{%- endif %}

[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under 98"
Expand Down
Loading