zosstorage/docs/adr/0001-modular-workflow.md

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.
     • 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 when decisions are refined/superseded.

  4. Examples and fixtures

     • Maintain comprehensive example configs in config/, beginning with config/zosstorage.example.yaml.

  5. Golden path to resume work

     • Read module headers, grep REGION markers, consult docs/API-SKELETONS.md and recent ADRs, and check 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/orchestrator/run.rs
  • src/cli/args.rs
  • src/device/discovery.rs
  • src/partition/plan.rs
  • src/fs/plan.rs
  • src/mount/ops.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
• API Index: docs/API-SKELETONS.md
• Specs: docs/SPECS.md
• Dev Workflow: docs/DEV_WORKFLOW.md
• Example Config: 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 when signatures change.
• Add new ADRs when we introduce significant architectural adjustments.