diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fdb4426..c101e97 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,26 +2,8 @@ -## Related Issues - - - -## Type of Change - - - ## Checklist -- [ ] `just lint` passes -- [ ] `just test` passes - [ ] Tests added or updated for the change - [ ] `README.md` updated if needed - [ ] Release label added diff --git a/copier.yml b/copier.yml index 7ff8472..07ddddd 100644 --- a/copier.yml +++ b/copier.yml @@ -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 @@ -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 diff --git a/justfile b/justfile index bf03158..6209821 100644 --- a/justfile +++ b/justfile @@ -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: diff --git a/template/.github/pull_request_template.md b/template/.github/pull_request_template.md.jinja similarity index 90% rename from template/.github/pull_request_template.md rename to template/.github/pull_request_template.md.jinja index fdb4426..fb1d268 100644 --- a/template/.github/pull_request_template.md +++ b/template/.github/pull_request_template.md.jinja @@ -5,6 +5,7 @@ ## Related Issues +{%- if use_releases %} ## Type of Change @@ -17,6 +18,7 @@ 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 @@ -24,4 +26,6 @@ Add a release label to this PR from the Labels section of the PR sidebar - [ ] `just test` passes - [ ] Tests added or updated for the change - [ ] `README.md` updated if needed +{%- if use_releases %} - [ ] Release label added +{%- endif %} diff --git a/template/.github/workflows/python.yml b/template/.github/workflows/python.yml.jinja similarity index 92% rename from template/.github/workflows/python.yml rename to template/.github/workflows/python.yml.jinja index 6486300..c215245 100644 --- a/template/.github/workflows/python.yml +++ b/template/.github/workflows/python.yml.jinja @@ -1,3 +1,4 @@ +{% raw -%} name: Python CI Checks on: @@ -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: @@ -48,3 +51,4 @@ jobs: uses: DavidAnson/markdownlint-cli2-action@21c1be1b93ad9ed58fa840aacc3f279cde2a72ff # v24.2.0 with: globs: "**/*.md" +{%- endraw %} diff --git a/template/.gitignore b/template/.gitignore index fe817c9..678402e 100644 --- a/template/.gitignore +++ b/template/.gitignore @@ -126,6 +126,8 @@ dmypy.json # Claude .claude/*.local.* +Claude.md.example +CLAUDE.md # Dev Container .devcontainer/devcontainer-lock.json diff --git a/template/CLAUDE.md.example.jinja b/template/CLAUDE.md.example.jinja index e315126..58c4ca6 100644 --- a/template/CLAUDE.md.example.jinja +++ b/template/CLAUDE.md.example.jinja @@ -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 ` / `uv add --dev ` - add a runtime / dev dependency (never edit `uv.lock` by hand) - `uv run {{ project_name }}` - run the app entry point @@ -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 }}. 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 @@ -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//` 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@ # vX.Y.Z`); run `just zizmor` after editing workflows @@ -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 %} diff --git a/template/README.md.jinja b/template/README.md.jinja index dd440c1..8eab4ab 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -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 @@ -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 diff --git a/template/justfile b/template/justfile.jinja similarity index 95% rename from template/justfile rename to template/justfile.jinja index f8d9db5..7085d30 100644 --- a/template/justfile +++ b/template/justfile.jinja @@ -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 @@ -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 diff --git a/template/prek.toml b/template/prek.toml.jinja similarity index 98% rename from template/prek.toml rename to template/prek.toml.jinja index 752635b..7c79836 100644 --- a/template/prek.toml +++ b/template/prek.toml.jinja @@ -32,6 +32,7 @@ hooks = [ entry = "just test", pass_filenames = false }, +{%- if use_docs %} { id = "docs-build", name = "docs build", @@ -40,6 +41,7 @@ hooks = [ files = "^(docs/|src/|zensical\\.toml$)", pass_filenames = false }, +{%- endif %} { id = "markdownlint", name = "markdownlint", diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index 1fffdfa..2a652a7 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -21,6 +21,7 @@ dev = [ "ruff>=0.17.3", "ty>=0.0.96", ] +{%- if use_docs %} docs = [ "mkdocstrings[python]>=1.0.8", "zensical>=0.1.0", @@ -28,6 +29,7 @@ docs = [ [tool.codespell] skip = "./site" # Built docs output +{%- endif %} [tool.pytest.ini_options] addopts = "--cov=src --cov-report=term-missing --cov-fail-under 98"