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.
This commit is contained in:
74
docs/adr/0001-modular-workflow.md
Normal file
74
docs/adr/0001-modular-workflow.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# 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.
|
||||
53
docs/adr/README.md
Normal file
53
docs/adr/README.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Architectural Decision Records (ADR) Index
|
||||
|
||||
Purpose
|
||||
- Central place to list and navigate all ADRs.
|
||||
- Naming scheme: `NNNN-title.md` (zero-padded sequence).
|
||||
|
||||
Index
|
||||
- [0001: Modular Development Workflow with Grep-able Contracts and Regions](0001-modular-workflow.md)
|
||||
|
||||
Conventions
|
||||
- Location: [docs/adr/](.)
|
||||
- Create new ADRs incrementally with next number (e.g., `0002-<short-title>.md`).
|
||||
- Each ADR should include:
|
||||
- Status (Proposed/Accepted/Deprecated)
|
||||
- Context
|
||||
- Decision
|
||||
- Consequences
|
||||
- Links to related docs (e.g., [docs/ARCHITECTURE.md](../ARCHITECTURE.md), [docs/API-SKELETONS.md](../API-SKELETONS.md))
|
||||
|
||||
Workflow
|
||||
1) Propose an ADR when a design decision impacts architecture or module boundaries.
|
||||
2) Add the ADR file under [docs/adr/](.) with the next sequence number.
|
||||
3) Append the ADR to this index under “Index”.
|
||||
4) Optionally add a short “Architectural Decisions” section to [docs/ARCHITECTURE.md](../ARCHITECTURE.md) summarizing the latest ADRs.
|
||||
|
||||
Template
|
||||
|
||||
```md
|
||||
# ADR NNNN: Title
|
||||
|
||||
Status
|
||||
- Proposed | Accepted | Deprecated
|
||||
- Date: YYYY-MM-DD
|
||||
|
||||
Context
|
||||
- Brief background and forces at play.
|
||||
|
||||
Decision
|
||||
- The choice made; bullet any alternatives considered.
|
||||
|
||||
Consequences
|
||||
- Pros/cons, impacts on modules, tests, build, etc.
|
||||
|
||||
Links
|
||||
- [docs/ARCHITECTURE.md](../ARCHITECTURE.md)
|
||||
- Related ADRs
|
||||
```
|
||||
|
||||
Validation ideas (optional future work)
|
||||
- Add a CI step or `cargo xtask adr-check` to verify:
|
||||
- Files match `NNNN-title.md`
|
||||
- All ADRs are listed in this README
|
||||
- Sequence numbers are contiguous
|
||||
Reference in New Issue
Block a user