generated from eblume/project-template
68 lines
3 KiB
Markdown
68 lines
3 KiB
Markdown
|
---
|
||
|
|
title: Reference
|
||
|
|
modified: 2026-04-19
|
||
|
|
tags:
|
||
|
|
- reference
|
||
|
|
- meta
|
||
|
|
---
|
||
|
|
|
||
|
|
# Reference
|
||
|
|
|
||
|
|
Technical reference material for the repository tooling that ships with this project.
|
||
|
|
|
||
|
|
## Template Surface Area
|
||
|
|
|
||
|
|
| Path | Purpose |
|
||
|
|
|------|---------|
|
||
|
|
| `.dagger/src/project_template_ci/` | Dagger module that builds the Quartz docs tarball used by releases |
|
||
|
|
| `.forgejo/workflows/build.yaml` | Generic CI validation workflow |
|
||
|
|
| `.forgejo/workflows/release.yaml` | Manual release workflow that versions, builds docs, and publishes release assets |
|
||
|
|
| `.forgejo/scripts/` | Optional project-specific hooks consumed by the workflows |
|
||
|
|
| `mise-tasks/` | Helper tasks for docs validation, Mikado chains, PR review, and runner inspection |
|
||
|
|
|
||
|
|
## Forgejo Workflows
|
||
|
|
|
||
|
|
### `build.yaml`
|
||
|
|
|
||
|
|
- Triggers on pushes to `main` and pull requests targeting `main`
|
||
|
|
- Runs `prek run --all-files`
|
||
|
|
- Executes `.forgejo/scripts/build` if that hook exists and is executable
|
||
|
|
- Otherwise exits after generic template validation
|
||
|
|
|
||
|
|
### `release.yaml`
|
||
|
|
|
||
|
|
- Triggered manually via `workflow_dispatch`
|
||
|
|
- Accepts `BUMP_PATCH`, `BUMP_MINOR`, `BUMP_MAJOR`, or `SPECIFIC_VERSION`
|
||
|
|
- Resolves the next version from the latest Forgejo release tag
|
||
|
|
- Builds `CHANGELOG.md` with towncrier when fragment files exist
|
||
|
|
- Builds `docs-<version>.tar.gz` via `dagger call build-docs --src=. --version=<version>`
|
||
|
|
- Executes `.forgejo/scripts/release <version>` if present to stage extra files under `release-assets/`
|
||
|
|
- Creates the Forgejo release and uploads the docs tarball plus any extra assets
|
||
|
|
- Commits generated changelog updates back to `main` when fragments were consumed
|
||
|
|
|
||
|
|
## Mise Tasks
|
||
|
|
|
||
|
|
| Task | Purpose |
|
||
|
|
|------|---------|
|
||
|
|
| `mise run ai-docs` | Print the key docs files AI agents are expected to read first |
|
||
|
|
| `mise run changelog-check` | Validate changelog fragments are flat files under `docs/changelog.d/` |
|
||
|
|
| `mise run docs-check-filenames` | Detect duplicate doc filenames |
|
||
|
|
| `mise run docs-check-frontmatter` | Validate required frontmatter fields |
|
||
|
|
| `mise run docs-check-index` | Ensure each doc is linked from its category index |
|
||
|
|
| `mise run docs-check-links` | Validate wiki-links against existing doc filenames |
|
||
|
|
| `mise run docs-mikado` | Inspect active Mikado chains and resume C2 work |
|
||
|
|
| `mise run docs-preview <tarball>` | Extract and serve a released docs tarball locally |
|
||
|
|
| `mise run mikado-branch-invariant-check` | Validate `mikado/*` branch commit discipline |
|
||
|
|
| `mise run pr-comments <pr_number>` | List unresolved PR comments |
|
||
|
|
| `mise run runner-logs [run_number]` | List Forgejo Actions runs or fetch logs for a job |
|
||
|
|
|
||
|
|
## Changelog Fragments
|
||
|
|
|
||
|
|
- Store towncrier fragments under `docs/changelog.d/`
|
||
|
|
- Use one flat `.md` file per change
|
||
|
|
- The directory may contain only `.gitkeep` until the first real fragment is added
|
||
|
|
|
||
|
|
## TODO After Templating
|
||
|
|
|
||
|
|
- TODO: Set `baseUrl` in `docs/quartz.config.ts` to the hosted docs domain, or `localhost` if the docs are only previewed locally
|
||
|
|
- TODO: Rename `.dagger/src/project_template_ci/` and the exported Dagger class to match the generated project
|