65 lines
1.3 KiB
Markdown
65 lines
1.3 KiB
Markdown
# Specifications
|
|
|
|
Formal Kaptan specifications should normally live next to the code item they govern.
|
|
|
|
Examples:
|
|
|
|
- `kaptan-runtime/src/control_loop.rs`
|
|
- `kaptan-runtime/src/control_loop.v0.1.0.spec.md`
|
|
- `kaptan-runtime/src/scheduler.rs`
|
|
- `kaptan-runtime/src/scheduler.v0.1.0.spec.md`
|
|
|
|
## Compile-Time Linking
|
|
|
|
Code implementations should link to their governing spec through `#[spec("...")]`.
|
|
|
|
Example:
|
|
|
|
```rust
|
|
use kaptan_spec::spec;
|
|
|
|
#[spec("control_loop.v0.1.0.spec.md")]
|
|
pub struct ControlLoop;
|
|
```
|
|
|
|
The attribute expands to a compile-time file inclusion guard. If the linked file does not exist, compilation fails.
|
|
|
|
## Spec Format
|
|
|
|
Formal specs are expected to declare these keys in YAML frontmatter:
|
|
|
|
- `title`
|
|
- `status`
|
|
- `owners`
|
|
|
|
Allowed statuses are:
|
|
|
|
- `in-progress`
|
|
- `implemented`
|
|
- `deprecated`
|
|
|
|
Owner entries must use full name and email address in this format:
|
|
|
|
```text
|
|
- Full Name <name@example.com>
|
|
```
|
|
|
|
The spec path is the identifier for linkage and traceability.
|
|
|
|
- The code path plus the `#[spec("...")]` reference identifies the governing spec.
|
|
- The version is part of the spec filename and therefore part of the spec identity.
|
|
|
|
## Template
|
|
|
|
Use this starter when creating a new colocated spec:
|
|
|
|
```markdown
|
|
---
|
|
title: Replace with title
|
|
status: in-progress
|
|
owners:
|
|
- Full Name <name@example.com>
|
|
---
|
|
|
|
# TODO
|
|
``` |