generated from eblume/project-template
Erich Blume
c266f7ee4a
Documents the desired end state before the code change (C1 docs-first): - release.yaml bumps the workspace version into a commit only the tag points at, keeping main at 0.0.0 - heph/hephd --version will report the release version plus the build SHA Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
---
|
|
title: Reference
|
|
modified: 2026-04-19
|
|
tags:
|
|
- reference
|
|
- meta
|
|
---
|
|
|
|
# Reference
|
|
|
|
Technical reference material for the repository tooling that ships with this project.
|
|
|
|
## Project
|
|
|
|
- [[v1-prototype-tech-spec]] — Hephaestus technical specification (data model, RPC API, "what is next?" ranking, recurrence, testing strategy, v1 scope)
|
|
- [[heph-nvim]] — The Neovim plugin surface: architecture, buffer-backed editing, RPC dependencies, commands, and the headless e2e harness
|
|
|
|
## Template Surface Area
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `.dagger/src/hephaestus_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, and commits the consumed fragments back to `main`
|
|
- Bumps the workspace version (`Cargo.toml` + `Cargo.lock`) to the release version in a commit that **only the release tag points at** — `main` deliberately stays at `0.0.0`, so `cargo install --git --tag vX.Y.Z` reports the real version while branch/dev installs report `0.0.0`
|
|
- Tags that bump commit `vX.Y.Z` and pushes the tag itself (the workflow tags manually rather than letting the release API create the tag)
|
|
- 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 for the pushed tag and uploads the docs tarball plus any extra assets
|
|
|
|
## 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 import-todoist` | Seed a heph store from Todoist (dry-run by default; `-- --commit` to write) — see [[import-todoist]] |
|
|
| `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 once published (currently `localhost`)
|