59 lines
4.6 KiB
Markdown
59 lines
4.6 KiB
Markdown
# Development
|
|
|
|
This is the first-read landing page for people and LLM coding agents working on
|
|
Narratio. It provides a concise repository orientation and routes each kind of
|
|
change to its canonical documentation.
|
|
|
|
Narratio is a stage-driven Go orchestrator for turning D&D session audio into
|
|
polished transcripts and generated artifacts. Start with the
|
|
[README](../README.md) for product context,
|
|
[Architecture](policy/architecture.md) for normative system boundaries, and the
|
|
[Internal Overview](internal/overview.md) for implemented component ownership.
|
|
|
|
## What To Read
|
|
|
|
| When working on | Read | Why |
|
|
| --- | --- | --- |
|
|
| Finding the package or component that owns current behavior | [Internal Overview](internal/overview.md) | It is the implemented component inventory and routes to focused internal documents. |
|
|
| Application shape, boundaries, dependency direction, runtime invariants, safety properties, or dependencies | [Architecture](policy/architecture.md) | It defines the intended system shape, ownership, and non-goals. |
|
|
| Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical owners, audiences, current-behavior rules, and maintenance requirements. |
|
|
| Adding, changing, reviewing, rewriting, or deleting tests | [Testing Policy](policy/testing.md) | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and test lifecycle decisions. |
|
|
| CLI composition or command behavior | [Internal Overview](internal/overview.md) and [CLI Reference](cli.md) | The overview routes to command ownership; the reference owns public syntax and invocation behavior. |
|
|
| Configuration loading, resolution, or user-visible configuration | [Internal Overview](internal/overview.md) and [Configuration](config.md) | The overview routes to implementation ownership; the reference owns fields, defaults, discovery, and validation. |
|
|
| Session workflow, status, restore, cleanup, or object storage | [Restore Internals](internal/command-restore.md), [Workspace Internals](internal/workspace.md), [Storage Internals](internal/storage.md), [Operations](operations.md), and [Troubleshooting](troubleshooting.md) | These separate implementation mechanics, operator procedures, and symptom-driven recovery. |
|
|
| Pipeline sequencing or the behavior of a stage | [Internal Overview](internal/overview.md) and its focused stage documents | The overview owns the implemented stage inventory and routes to each stage contract. |
|
|
| Adapters or external tool contracts | [Adapter Internals](internal/adapters.md) and [Integration Contracts](integrations/README.md) | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. |
|
|
| Manifests, artifacts, workspace paths, or publish behavior | [Manifest Internals](internal/manifest.md), [Artifact Internals](internal/artifacts.md), [Workspace Internals](internal/workspace.md), [Publish Internals](internal/stage-publish.md), and [Operations](operations.md) | These separate implementation state and resolution from operator-visible layout and lifecycle. |
|
|
| Maintained configuration or input examples | [Configuration](config.md) and [Examples](../examples/README.md) | The reference owns field meanings; the examples directory owns complete copyable files. |
|
|
| Proposed or unimplemented behavior | `docs/roadmap/` | Future work belongs only in roadmap documentation until implemented. |
|
|
|
|
For an existing subsystem, also inspect its focused tests and package-level
|
|
contracts before changing behavior.
|
|
|
|
## Validation
|
|
|
|
Use focused package tests while iterating. Every pull request and push runs the
|
|
following repository-wide checks before it can be accepted:
|
|
|
|
```sh
|
|
go test ./...
|
|
go test -race ./...
|
|
go vet ./...
|
|
go build ./...
|
|
go test ./internal/doccheck
|
|
go test ./internal/config -run '^TestExamplesLoadAndValidate$'
|
|
```
|
|
|
|
The documentation check verifies local Markdown links and the dependency graph
|
|
of the Woodpecker workflows. The configuration check loads every maintained
|
|
pipeline and session example. Release automation repeats these checks and
|
|
cross-compiles the CLI before it builds release assets; publishing depends on
|
|
that validation path, so a failure cannot publish a release.
|
|
|
|
Woodpecker also runs `go test -race -shuffle=on -count=3 ./...` on its scheduled
|
|
job to expose ordering and repeatability defects. Current runners cross-compile
|
|
for macOS and Windows, but do not provide native macOS or Windows execution.
|
|
Those cross-builds establish compilation only, not platform-equivalent runtime
|
|
evidence. Add native checks only when official runner labels and successful
|
|
native-run evidence are available.
|