111 lines
3.9 KiB
Markdown
111 lines
3.9 KiB
Markdown
# Development Policy
|
|
|
|
## Purpose
|
|
|
|
This document defines contributor workflow for maintainers and coding agents.
|
|
It complements [architecture policy](architecture.md) and
|
|
[documentation policy](documentation.md).
|
|
|
|
## Repository layout
|
|
|
|
- `cmd/seriatim/`: process entrypoint.
|
|
- `internal/cli/`: Cobra commands and flag wiring.
|
|
- `internal/config/`: option normalization and validation.
|
|
- `internal/pipeline/`: orchestration interfaces, registry, runner.
|
|
- `internal/builtin/`: implemented input/pre/post/output modules and merger.
|
|
- `internal/artifact/`: conversion from internal merged model to public shapes.
|
|
- `internal/trim/`: artifact-level trim logic.
|
|
- `internal/normalize/`: artifact-level normalize parsing/building.
|
|
- `internal/*` domain packages: overlap, coalesce, danglers, filler,
|
|
backchannel, speaker, autocorrect, report, model.
|
|
- `schema/`: public structs plus embedded JSON Schemas and validation.
|
|
- `docs/`: policy, user docs, roadmap, and internal docs.
|
|
|
|
## Local checks
|
|
|
|
Primary repository check:
|
|
|
|
```sh
|
|
go test ./...
|
|
```
|
|
|
|
Useful manual checks for CLI-facing changes:
|
|
|
|
```sh
|
|
go run ./cmd/seriatim --help
|
|
go run ./cmd/seriatim merge --help
|
|
go run ./cmd/seriatim trim --help
|
|
go run ./cmd/seriatim normalize --help
|
|
```
|
|
|
|
Current toolchain note:
|
|
|
|
- There is no Makefile.
|
|
- There is no taskfile.
|
|
- There is no committed linter configuration.
|
|
- There is no automated documentation checker.
|
|
|
|
## Coding conventions
|
|
|
|
- Keep core behavior deterministic for identical inputs/config/version.
|
|
- Keep CLI command functions thin: parse flags, construct config, delegate.
|
|
- Keep validation in `internal/config` and package-specific validators.
|
|
- Return errors from deep logic; do not print inside internal packages.
|
|
- Preserve clear package boundaries between adapters and domain transforms.
|
|
|
|
## Dependency policy
|
|
|
|
Prefer the Go standard library first.
|
|
|
|
Third-party dependencies should stay narrow and justified. Current direct
|
|
runtime dependencies are:
|
|
|
|
- `github.com/spf13/cobra` for CLI structure.
|
|
- `gopkg.in/yaml.v3` for YAML rule files.
|
|
- `github.com/santhosh-tekuri/jsonschema/v6` for public schema validation.
|
|
|
|
## Adding CLI flags
|
|
|
|
1. Add the flag in the relevant `internal/cli/*.go` command.
|
|
2. Thread the raw value through `config.*Options`.
|
|
3. Add normalization/validation in `internal/config/config.go`.
|
|
4. Update or add CLI/config tests.
|
|
5. Update canonical docs (`docs/cli.md`, `docs/config.md`) if user-visible.
|
|
|
|
## Adding config fields or environment variables
|
|
|
|
1. Add field(s) to the relevant config struct(s).
|
|
2. Parse and validate in `internal/config/config.go`.
|
|
3. Add tests in `internal/config/config_test.go`.
|
|
4. Thread validated values into consuming modules.
|
|
5. Update `docs/config.md` and related docs.
|
|
|
|
## Adding modules or pipeline behavior
|
|
|
|
1. Implement the module in the appropriate package (often `internal/builtin`).
|
|
2. Expose a stable module name via `Name()`.
|
|
3. Register it in `internal/builtin/registry.go`.
|
|
4. Ensure preprocessing modules declare correct `Requires()`/`Produces()`
|
|
states.
|
|
5. Add/adjust tests in module packages and `internal/cli/merge_test.go`.
|
|
6. Document internal behavior changes in `docs/internal/`.
|
|
|
|
## Schema and artifact changes
|
|
|
|
1. Update public structs and validation logic in `schema/`.
|
|
2. Update embedded JSON Schema files (`schema/*.schema.json`) if contract
|
|
changes.
|
|
3. Update conversion behavior in `internal/artifact`, `internal/trim`, and/or
|
|
`internal/normalize` as needed.
|
|
4. Add tests in `schema/`, `internal/artifact/`, `internal/trim/`,
|
|
`internal/normalize/`, and CLI tests.
|
|
5. Update user and internal docs that reference output contracts.
|
|
|
|
## Documentation expectations
|
|
|
|
- Outside `docs/roadmap/`, document only implemented behavior.
|
|
- Keep canonical homes: CLI in `docs/cli.md`, config in `docs/config.md`,
|
|
operations in `docs/operations.md`, troubleshooting in
|
|
`docs/troubleshooting.md`, internals in `docs/internal/`.
|
|
- When behavior changes, update docs in the same change.
|