Files

Jan De Landtsheer 507bc172c2 feat: first-draft preview-capable zosstorage

- CLI: add topology selection (-t/--topology), preview flags (--show/--report), and removable policy override (--allow-removable) (src/cli/args.rs)
- Config: built-in sensible defaults; deterministic overlays for logging, fstab, removable, topology (src/config/loader.rs)
- Device: discovery via /proc + /sys with include/exclude regex and removable policy (src/device/discovery.rs)
- Idempotency: detection via blkid; safe emptiness checks (src/idempotency/mod.rs)
- Partition: topology-driven planning (Single, DualIndependent, BtrfsRaid1, SsdHddBcachefs) (src/partition/plan.rs)
- FS: planning + creation (mkfs.vfat, mkfs.btrfs, bcachefs format) and UUID capture via blkid (src/fs/plan.rs)
- Orchestrator: pre-flight with preview JSON (disks, partition_plan, filesystems_planned, mount scheme). Skips emptiness in preview; supports stdout+file (src/orchestrator/run.rs)
- Util/Logging/Types/Errors: process execution, tracing, shared types (src/util/mod.rs, src/logging/mod.rs, src/types.rs, src/errors.rs)
- Docs: add README with exhaustive usage and preview JSON shape (README.md)

Builds and unit tests pass: discovery, util, idempotency helpers, and fs parser tests.

2025-09-29 11:37:07 +02:00

3.7 KiB

Raw Blame History

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:
Remaining modules will follow the same pattern as needed (e.g., util, idempotency, main/lib if helpful).

3.7 KiB Raw Blame History

ADR 0001: Modular Development Workflow with Grep-able Contracts and Regions

3.7 KiB

Raw Blame History