Repository navigation
Expand file tree
/
Copy pathREADME.md.jinja
More file actions
106 lines (85 loc) · 5.66 KB
/
Copy pathREADME.md.jinja
File metadata and controls
106 lines (85 loc) · 5.66 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# {{ project_name }}
[](https://github.com/{{ github_repo }}/actions/workflows/python.yml)
[](https://github.com/{{ github_repo }}/actions/workflows/security.yml)
[](https://github.com/betterleaks/betterleaks)
[](https://zizmor.sh/)
{{ description }}
## Setup
Project supports local development and VSCode Dev container development
### Local Development Installation
Note: Project uses `uv` and `just` to
manage project configuration and commands
* Install tools and sync the project - `just setup` (runs `brew bundle install`, then `just sync`)
### VS Code Dev Container
* Install Docker
* Install VSCode
* Open project folder in VS Code
* Install recommended extensions
* Reopen in container using Remote Development Container menu
## Project 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, spell check (typos), and lint workflows (actionlint), YAML (yamllint),
and JSON (jq) (applies fixes)
* `just ci-lint` - run the same checks without modifying files, except spell check (used in CI)
* `just spellcheck` - check spelling with typos
* `just test` - run unit tests
* `just coverage` - run unit tests with coverage (fails under 98%)
* `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 betterleaks` - scan staged changes for secrets with betterleaks
* `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 %}
* `just update-template` - pull in the latest changes from the Copier template
* `uv add {package}` - install a dependency
## CI and Security
| Workflow | Runs on | Purpose |
| --------------------- | ----------------------- | ------------------------------------------------------- |
{%- if use_docs %}
| `python.yml` | push / PR to `main` | lint, spell check, unit tests, docs build, markdownlint |
{%- else %}
| `python.yml` | push / PR to `main` | lint, spell check, unit tests, markdownlint |
{%- endif %}
| `security.yml` | push to `main`, all PRs | zizmor, betterleaks, 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 weekly 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
Releases are managed with [Release Drafter](https://github.com/release-drafter/release-drafter),
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; any other repository labels you add are ignored.
| Release label | Version bump | Release notes section |
| ----------------------------------------------------------------- | ------------ | --------------------- |
| `breaking` | major | Breaking Changes |
| `feature`, `enhancement` | minor | Features |
| `bug`, `fix` | patch | Bug Fixes |
| `chore`, `ci`, `dependencies`, `documentation`, `refactor` | patch | Maintenance |
| `skip-changelog` | none | Excluded |
* Every PR must have at least one release label, or the `Release Drafter / require-label` check fails. If a release
has PRs with different labels, the largest bump wins
* Release labels are added automatically from the PR's branch name prefix (`feat/`, `fix/`, `chore/`,
`ci/`, `docs/`, `refactor/`) and from the files it changes. You can add or change them by hand
* Run `just set-github-labels` once to create the release labels in the GitHub repository
* 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
* Usage Notes