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
16 changes: 16 additions & 0 deletions .github/workflows/python.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,19 @@ jobs:
- name: Unit tests
run: |
just test
- name: Docs build
run: |
just docs-build
markdownlint:
runs-on: ubuntu-slim
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Keep markdownlint-cli2 in step with the VS Code markdownlint extension
- name: Markdownlint
uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24.2.0
with:
globs: "**/*.md"
21 changes: 21 additions & 0 deletions .github/workflows/security.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,27 @@ jobs:
uses: zizmorcore/zizmor-action@45d7276c9ca790aabd705e31ca99c6185c3e76dd # v0.8.1
with:
advanced-security: false
pip-audit:
runs-on: ubuntu-slim
permissions:
contents: read
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install uv
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
with:
enable-cache: false
version: ">=0.13,<0.14"
- name: Setup environment
run: |
uv tool install rust-just
just sync
- name: Audit dependencies
run: |
just audit
gitleaks:
runs-on: ubuntu-slim
steps:
Expand Down
11 changes: 10 additions & 1 deletion .markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
@@ -1,6 +1,15 @@
{
// Rule configuration
"config": {
// Line length
"MD013": {
"line_length": 120
}
},
// Files excluded from markdown linting (glob syntax)
"ignores": [
".github/pull_request_template.md"
".github/pull_request_template.md",
".venv/**",
"site/**"
]
}
1 change: 1 addition & 0 deletions Brewfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
brew "gitleaks"
brew "just"
brew "markdownlint-cli2"
brew "uv"
brew "zizmor"
8 changes: 0 additions & 8 deletions CHANGELOG.md

This file was deleted.

13 changes: 10 additions & 3 deletions CLAUDE.md.example
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,18 @@ Python project template using `uv` for environment/dependency management and `ju

- `just setup` - install Homebrew tools (`Brewfile`) and sync the project
- `just sync` - install all dependency groups into `.venv`
- `just lint` - type check (ty), lint + autofix (ruff), format (ruff), spell check (codespell)
- `just lint` - type check (ty), lint + autofix (ruff), format (ruff), spell check (codespell),
workflow lint (actionlint)
- `just ci-lint` - same checks without modifying files (used to verify, not fix)
- `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`)
- `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
- `just zizmor` - audit GitHub Actions workflows for security issues
- `just git-leaks` - scan staged changes for secrets
- `just set-github-labels` - create/update the release labels on GitHub (`scripts/sync-labels.sh`, needs `gh`)
- `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)
- `uv add <pkg>` / `uv add --dev <pkg>` - add a runtime / dev dependency (never edit `uv.lock` by hand)
- `uv run example` - run the app entry point

Expand All @@ -23,7 +29,8 @@ Run `just lint` and `just test` before considering a change done.
- `src/example/__init__.py` - `main()` entry point, exposed as the `example` script
- `tests/` - pytest tests; import the package as `from example.<module> import ...`
- `prek.toml` - git hook config (`prek install` to enable)
- `.github/workflows/` - `python.yml` (lint + tests), `security.yml` (zizmor, gitleaks),
- `.github/workflows/` - `python.yml` (lint, tests, docs build, markdownlint),
`security.yml` (zizmor, gitleaks, pip-audit),
`release-drafter.yml` (draft release, PR labels), `release.yml` (manual release)
- `.github/release-drafter.yml` - release label → version bump / release notes section mapping
- `.github/dependabot.yml` - weekly updates for actions, uv, dev container image and features
Expand Down
23 changes: 14 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,23 +29,28 @@ manage project configuration and commands

* `just setup` - install Homebrew tools from the `Brewfile` and sync the project
* `just sync` - sync project dependencies (all groups)
* `just lint` - type check, lint, format, and spellcheck project files (applies fixes)
* `just lint` - type check, lint, format, spellcheck, and lint workflows (actionlint) (applies fixes)
* `just ci-lint` - run the same checks without modifying files (used in CI)
* `just test` - run unit tests
* `just audit` - check dependencies for known vulnerabilities with pip-audit
* `just markdownlint` - lint Markdown files with markdownlint-cli2
* `just docs-build` - build the docs site with Zensical (strict mode, output in `site/`)
* `just docs-serve` - serve the docs locally with live reload
* `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
* `just set-github-labels` - create or update the release labels on GitHub (requires `gh auth login`)
* `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`)
* `uv add {package}` - install a dependency

## CI and Security

| Workflow | Runs on | Purpose |
| ------------------------------------------------- | ---------------------------- | ---------------------------------------------- |
| `python.yml` | push / PR to `main` | lint and unit tests |
| `security.yml` | push to `main`, all PRs | zizmor workflow audit, gitleaks secret scan |
| `release-drafter.yml` | push to `main`, PRs | update the draft release, label PRs |
| `release.yml` | manual | publish a release |
| Workflow | Runs on | Purpose |
| --------------------- | ----------------------- | -------------------------------------------- |
| `python.yml` | push / PR to `main` | lint, unit tests, docs build, markdownlint |
| `security.yml` | push to `main`, all PRs | zizmor, gitleaks, pip-audit dependency audit |
| `release-drafter.yml` | push to `main`, PRs | update the draft release, label PRs |
| `release.yml` | manual | publish a release |

* 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
Expand All @@ -60,7 +65,7 @@ which reads the **release labels** on merged pull requests.
A release label is a GitHub label added to the pull request itself, from the **Labels** section
of the PR sidebar. Release Drafter only reads these labels. Commit messages and PR titles are not
parsed, so prefixes like `feat:` or `fix:` have no effect. Only the labels below count as release
labels; other repository labels (e.g. `good first issue`, `question`) are ignored.
labels; any other repository labels you add are ignored.

| Release label | Version bump | Release notes section |
| ----------------------------------------------------------------- | ------------ | --------------------- |
Expand Down
7 changes: 7 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# example

Baseline Python project template.

* Build the docs with `just docs-build`
* Add pages under `docs/` and list them in `nav` in `zensical.toml`
* See the [API Reference](reference.md) for documentation generated from docstrings
3 changes: 3 additions & 0 deletions docs/reference.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# API Reference

::: example.hello_world
27 changes: 27 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
@@ -1,25 +1,52 @@
# List available recipes
[private]
default:
@just --list
# Check dependencies for known vulnerabilities (pip-audit)
audit:
uv run pip-audit --skip-editable
# Type check, lint, format check, spell check, and lint workflows without changing files
ci-lint:
uv run ty check
uv run ruff check .
uv run ruff format --check .
uv run codespell
uv run actionlint
# 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
# Scan staged changes for secrets
git-leaks:
gitleaks git --pre-commit --staged --redact
# Type check, lint, format, spell check, and lint workflows, applying fixes
lint:
uv run ty check
uv run ruff check . --fix
uv run ruff format .
uv run codespell
uv run actionlint
# Lint Markdown files
markdownlint:
markdownlint-cli2 "**/*.md"
# Run the git hooks on staged files
prek:
uv run prek
# Remove non-release default labels and sync the release labels on GitHub
set-github-labels:
./scripts/sync-labels.sh
# Install Homebrew tools and sync the project
setup:
brew bundle install
just sync
# Install all dependency groups into .venv
sync:
uv sync --all-groups
# Run unit tests with coverage
test:
uv run pytest
# Audit GitHub Actions workflows for security issues
zizmor:
zizmor . --collect all
24 changes: 24 additions & 0 deletions prek.toml
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,30 @@ hooks = [
entry = "just test",
pass_filenames = false
},
{
id = "docs-build",
name = "docs build",
language = "system",
entry = "just docs-build",
files = "^(docs/|src/|zensical\\.toml$)",
pass_filenames = false
},
{
id = "markdownlint",
name = "markdownlint",
language = "system",
entry = "just markdownlint",
files = "\\.md$",
pass_filenames = false
},
{
id = "pip-audit",
name = "pip-audit",
language = "system",
entry = "just audit",
files = "^(pyproject\\.toml|uv\\.lock)$",
pass_filenames = false
},
{
id = "git-leaks",
name = "git leaks",
Expand Down
11 changes: 9 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,22 @@ build-backend = "uv_build"

[dependency-groups]
dev = [
"actionlint-py>=1.7.12.25",
"codespell>=2.4.3",
"pip-audit>=2.10.1",
"prek>=0.5.10",
"pytest",
"pytest-cov",
"ruff>=0.17.3",
"ty>=0.0.96",
]
docs = [
"mkdocstrings[python]>=1.0.8",
"zensical>=0.1.0",
]

[tool.codespell]
skip = "./site" # Built docs output

[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under 98"
Expand All @@ -29,12 +36,12 @@ addopts = "--cov=src --cov-report=term-missing --cov-fail-under 98"
line-length = 100

[tool.ruff.lint]
select = ["B", "E", "F", "W", "I", "N", "PT", "D", "UP", "RUF", "SIM"] # Choose your rule categories
select = ["B", "E", "F", "W", "I", "N", "PT", "D", "UP", "RUF", "SIM", "S", "C4", "PTH", "PL", "PERF"] # Choose your rule categories
ignore = ["D100", "D104", "D211", "D203", "D213", "D400", "D401", "D415"]
extend-ignore = ["E501"] # Line too long (handled by formatter)

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["D"] # Ignore docstring (D) errors in tests
"tests/*" = ["D", "S101"] # Ignore docstring (D) and assert (S101) errors in tests

[tool.ruff.format]
quote-style = "double"
Expand Down
23 changes: 22 additions & 1 deletion scripts/sync-labels.sh
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
#!/usr/bin/env bash
# Create or update the release labels used by Release Drafter.
# Remove GitHub's default labels that are not release labels, then create or update the
# release labels used by Release Drafter. Intended for fresh repositories: deleting a label
# also removes it from any issues and PRs that have it.
# Usage: scripts/sync-labels.sh [owner/repo] (defaults to the current repo)
set -euo pipefail

Expand All @@ -22,6 +24,25 @@ labels=(
"skip-changelog|cccccc|Exclude from release notes"
)

# GitHub's default labels that are not release labels
# (bug, documentation, and enhancement are defaults too, but are updated below)
default_labels=(
"duplicate"
"good first issue"
"help wanted"
"invalid"
"question"
"wontfix"
)

existing=$(gh label list --limit 1000 --json name --jq '.[].name')
for name in "${default_labels[@]}"; do
if grep -qxF "$name" <<< "$existing"; then
gh label delete "$name" --yes
echo "deleted: $name"
fi
done

for entry in "${labels[@]}"; do
IFS='|' read -r name color description <<< "$entry"
gh label create "$name" --color "$color" --description "$description" --force
Expand Down
Loading
Loading