74 lines
3.7 KiB
Markdown
74 lines
3.7 KiB
Markdown
# ADR 0001: Modular Development Workflow with Grep-able Contracts and Regions
|
|
|
|
Status
|
|
- Accepted
|
|
- Date: 2025-09-25
|
|
|
|
Context
|
|
- The project will be developed iteratively with frequent returns and feature additions. We need a workflow that avoids re-reading the entire tree to find context.
|
|
- APIs should remain stable and discoverable, with a single source of truth for contracts and invariants.
|
|
- Contributors should be able to quickly grep the repository and see where to implement behavior, extend via hooks, and understand safety/error mapping.
|
|
|
|
Decision
|
|
- Adopt a modular development workflow comprising:
|
|
1) Contract-first documentation
|
|
- Keep canonical API declarations in [docs/API-SKELETONS.md](docs/API-SKELETONS.md).
|
|
- Mirror these contracts in module headers and doc comments.
|
|
|
|
2) Grep-friendly REGION markers in source files
|
|
- Each module (where applicable) starts with compact region markers:
|
|
- REGION: API — one-liners listing public items and signatures
|
|
- REGION: RESPONSIBILITIES — scope/non-goals
|
|
- REGION: EXTENSION_POINTS — how to extend without rewriting
|
|
- REGION: SAFETY — invariants and safety/idempotency constraints
|
|
- REGION: ERROR_MAPPING — standard mapping to error types
|
|
- REGION: TODO — active work or future steps
|
|
- These markers enable quick discovery via grep without deep reading.
|
|
|
|
3) ADRs for architectural decisions
|
|
- Document significant structural or process choices in docs/adr/.
|
|
- Cross-link in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) when decisions are refined/superseded.
|
|
|
|
4) Examples and fixtures
|
|
- Maintain comprehensive example configs in config/, beginning with [config/zosstorage.example.yaml](config/zosstorage.example.yaml).
|
|
|
|
5) Golden path to resume work
|
|
- Read module headers, grep REGION markers, consult [docs/API-SKELETONS.md](docs/API-SKELETONS.md) and recent ADRs, and check [docs/SPECS.md](docs/SPECS.md) for in-progress notes.
|
|
|
|
Consequences
|
|
- Pros
|
|
- Fast onboarding and re-entry; contributors quickly find affected code by grepping markers or function names.
|
|
- Clear boundaries and invariants reduce coupling across modules.
|
|
- Documentation remains synchronized with code via consistent, enforceable patterns.
|
|
|
|
- Cons
|
|
- Slight overhead to keep REGION markers and API docs updated.
|
|
- Requires discipline to maintain concise one-liners and avoid duplication.
|
|
|
|
Implementation Notes
|
|
- Region markers have been added to key modules:
|
|
- [src/config/loader.rs](../src/config/loader.rs)
|
|
- [src/orchestrator/run.rs](../src/orchestrator/run.rs)
|
|
- [src/cli/args.rs](../src/cli/args.rs)
|
|
- [src/device/discovery.rs](../src/device/discovery.rs)
|
|
- [src/partition/plan.rs](../src/partition/plan.rs)
|
|
- [src/fs/plan.rs](../src/fs/plan.rs)
|
|
- [src/mount/ops.rs](../src/mount/ops.rs)
|
|
- [src/report/state.rs](../src/report/state.rs)
|
|
- Remaining modules will follow the same pattern as needed (e.g., util, idempotency, main/lib if helpful).
|
|
|
|
Related Documents
|
|
- Architecture: [docs/ARCHITECTURE.md](../ARCHITECTURE.md)
|
|
- API Index: [docs/API-SKELETONS.md](../API-SKELETONS.md)
|
|
- Specs: [docs/SPECS.md](../SPECS.md)
|
|
- Dev Workflow: [docs/DEV_WORKFLOW.md](../DEV_WORKFLOW.md)
|
|
- Example Config: [config/zosstorage.example.yaml](../../config/zosstorage.example.yaml)
|
|
|
|
Alternatives Considered
|
|
- Heavy code generation for interface docs — rejected due to complexity and limited incremental value for a small codebase.
|
|
- Relying solely on doc comments — insufficient discoverability without grep-able structured markers.
|
|
|
|
Adoption Plan
|
|
- Keep REGION markers up to date with each change to public APIs and module scope.
|
|
- Update [docs/API-SKELETONS.md](../API-SKELETONS.md) when signatures change.
|
|
- Add new ADRs when we introduce significant architectural adjustments. |