diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 14eaa73..67b04ab 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -12,6 +12,7 @@ /docs/API-STABILITY.md @XKush /docs/JSON-SCHEMA.md @XKush /docs/RELEASE-CRITERIA.md @XKush +/docs/rfc/ @XKush # CI & automation /.github/workflows/ @XKush diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6efc701..4238121 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,9 @@ Questions like “should I use `health` or `doctor`?” belong in **Discussions* 2. Keep changes focused — one problem per PR 3. Do **not** change the locked platform execution stack without maintainer sign-off (see `internal-docs/charter/PLATFORM-SPEC-SIGNOFF.md`) 4. JSON / CLI changes: read [API-STABILITY.md](docs/API-STABILITY.md) and [JSON-SCHEMA.md](docs/JSON-SCHEMA.md) -5. New features: check [MANIFESTO.md](docs/MANIFESTO.md) and [PROJECT-PRINCIPLES.md](docs/PROJECT-PRINCIPLES.md) first -6. Maintainers cutting a release: [RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md) +5. New features: check [MANIFESTO.md](docs/MANIFESTO.md) and [PROJECT-PRINCIPLES.md](docs/PROJECT-PRINCIPLES.md) first +6. **Large ideas** (plugins, new CLI, API breaks): [RFC process](docs/rfc/README.md) — **no implementation code** until RFC Accepted +7. Maintainers cutting a release: [RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md) Script layout: [`scripts/README.md`](scripts/README.md) · [Repository surface](docs/product/REPOSITORY-SURFACE.md) @@ -42,6 +43,6 @@ Include: Windows version, PowerShell version (`$PSVersionTable`), `devshell heal ## v3 stabilization (current phase) -We are **not** adding new public CLI commands in v3.0.x. Focus: bugfix, docs, tests, feedback. Feature ideas → Discussions first. +We are **not** adding new public CLI commands in v3.0.x. Focus: bugfix, docs, tests, feedback. Large ideas → [RFC](docs/rfc/README.md) first; small questions → Discussions. Contract: [ROADMAP.md](docs/ROADMAP.md) · Principles: [PROJECT-PRINCIPLES.md](docs/PROJECT-PRINCIPLES.md) · [MANIFESTO.md](docs/MANIFESTO.md) · Releases: [RELEASE-CRITERIA.md](docs/RELEASE-CRITERIA.md) diff --git a/README.md b/README.md index 465e388..b8096c7 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,7 @@ Full layout: [docs/product/REPOSITORY-SURFACE.md](docs/product/REPOSITORY-SURFAC | [Project principles](docs/PROJECT-PRINCIPLES.md) | Engineering guardrails | | [Manifesto](docs/MANIFESTO.md) | Why we exist · what we never do | | [Release criteria](docs/RELEASE-CRITERIA.md) | Pre-tag checklist for maintainers | +| [RFC process](docs/rfc/README.md) | Large ideas before code (plugins, API changes) | | [Troubleshooting](docs/TROUBLESHOOTING.md) | When doctor fails | | [Privacy](docs/PRIVACY.md) | Privacy configuration module | | [API stability](docs/API-STABILITY.md) | Frozen CLI contract (v3+) | diff --git a/docs/MANIFESTO.md b/docs/MANIFESTO.md index 4e3fbaf..953f9e4 100644 --- a/docs/MANIFESTO.md +++ b/docs/MANIFESTO.md @@ -2,6 +2,8 @@ One page on **why** this project exists and **what it refuses to become**. +We optimize for **trust**, not feature count. Trust comes from consistent decisions over a long time — not from shipping the largest PowerShell toolkit. + --- ## Why we exist diff --git a/docs/PROJECT-PRINCIPLES.md b/docs/PROJECT-PRINCIPLES.md index 9dce629..277bfd6 100644 --- a/docs/PROJECT-PRINCIPLES.md +++ b/docs/PROJECT-PRINCIPLES.md @@ -34,7 +34,7 @@ Engineering guardrails for contributors and future maintainers. When in doubt, p | Before you… | Read | |-------------|------| -| Propose a feature | [MANIFESTO](MANIFESTO.md) · [ROADMAP](ROADMAP.md) | +| Propose a feature | [MANIFESTO](MANIFESTO.md) · [ROADMAP](ROADMAP.md) · [RFC](rfc/README.md) if large | | Change JSON output | [JSON-SCHEMA](JSON-SCHEMA.md) | | Change architecture | New [ADR](adr/) | | Cut a release | [RELEASE-CRITERIA](RELEASE-CRITERIA.md) | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 166f5db..339dcb2 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -42,12 +42,12 @@ Explored **after** stabilization feedback — not committed dates: | Area | Notes | |------|--------| -| **Plugin API** | `plugins/` — Docker, WSL, VS Code, Azure, AWS, GitHub, Rust, Go | +| **Plugin API** | `plugins/` — see [RFC index](rfc/README.md) (Docker, WSL, …) | | **History** | Richer trends, export, compare | | **HTML reports** | Deeper styling, shareable bundles | | **Integrations** | GitHub Actions templates, Intune-friendly JSON | -Ideas → [Discussions](https://github.com/XKush/homebase-devshell/discussions) · label `idea` +Ideas → [RFC](rfc/README.md) (large) or [Discussions](https://github.com/XKush/homebase-devshell/discussions) (small) --- diff --git a/docs/rfc/README.md b/docs/rfc/README.md new file mode 100644 index 0000000..8c47c27 --- /dev/null +++ b/docs/rfc/README.md @@ -0,0 +1,68 @@ +# RFC process + +**Request for Comments** — how large ideas enter HomeBase DevShell. + +> Goal shift: we are not optimizing for “the biggest PowerShell toolkit.” +> We are building a project **people trust** — through consistent decisions over time. + +## Pipeline (order matters) + +``` +RFC (proposal, no code) + ↓ +Discussion (GitHub) + ↓ +Feedback (community + maintainers) + ↓ +ADR (if architecture/policy changes) + ↓ +Implementation (PR + tests) +``` + +**Not the reverse.** No plugin code, no new frozen CLI commands, no JSON schema breaks until an RFC is **Accepted**. + +## When you need an RFC + +| Need RFC | No RFC needed | +|----------|----------------| +| New plugin (Docker, WSL, VS Code, …) | Doc typo, troubleshooting line | +| New public CLI command | Bug fix in existing command | +| Breaking JSON / API change | Additive JSON field (minor) | +| Core health dashboard behavior change | Smoke test assertion | +| Platform orchestrator change | Internal refactor without behavior change | + +Check [MANIFESTO](MANIFESTO.md) and [PROJECT-PRINCIPLES](PROJECT-PRINCIPLES.md) before drafting. + +## RFC states + +| State | Meaning | +|-------|---------| +| **Proposed** | Open for comment — do not implement | +| **Accepted** | Maintainers approved — implementation may start | +| **Rejected** | Will not pursue (reason documented) | +| **Superseded** | Replaced by a newer RFC | + +## How to propose + +1. Copy [RFC-0000-template.md](RFC-0000-template.md) → `RFC-NNNN-short-title.md` +2. Open a [Discussion](https://github.com/XKush/homebase-devshell/discussions) (category **Ideas**) linking the RFC +3. PR only the RFC markdown — **no product code** in the same PR +4. After acceptance, maintainer updates status → **Accepted**, then optional ADR, then implementation PRs + +## Index + +| RFC | Title | Status | +|-----|-------|--------| +| [RFC-0001](RFC-0001-docker-plugin.md) | Docker plugin | Proposed | +| [RFC-0002](RFC-0002-wsl-plugin.md) | WSL plugin | Proposed | + +Accepted RFCs may reference ADRs in [../adr/](../adr/). + +## Relationship to other docs + +| Doc | Role | +|-----|------| +| **RFC** | *Should we?* — design proposal before code | +| **ADR** | *Why we did* — recorded decision after consensus | +| **ROADMAP** | *When we ship* — contract by version | +| **API-STABILITY** | *What we must not break* | diff --git a/docs/rfc/RFC-0000-template.md b/docs/rfc/RFC-0000-template.md new file mode 100644 index 0000000..3ed105e --- /dev/null +++ b/docs/rfc/RFC-0000-template.md @@ -0,0 +1,61 @@ +# RFC-0000: Template + +**Status:** Template (do not accept) +**Author:** <name> +**Created:** YYYY-MM-DD +**Discussion:** <link to GitHub Discussion> + +--- + +## Summary + +One paragraph: what problem this solves and for whom. + +## Motivation + +- Why now? +- Who asked for it (users, CI, enterprise)? +- How does it align with [MANIFESTO](../MANIFESTO.md)? + +## User experience + +What does the user run or see? Prefer extending `devshell health` over new top-level commands. + +## Design + +### Scope + +What is in / out? + +### Integration + +- Core vs `plugins/` +- JSON report impact (`healthSchemaVersion` / `reportSchemaVersion`) +- Offline behavior + +### Security & trust + +- Reversible? +- Defender / Firewall / anonymity boundaries per [PROJECT-PRINCIPLES](../PROJECT-PRINCIPLES.md) + +## Alternatives considered + +| Option | Why not | +|--------|---------| +| … | … | + +## Drawbacks + +What we give up; maintenance cost. + +## Unresolved questions + +- [ ] … + +## Implementation plan (after acceptance only) + +1. ADR if needed +2. Tests first +3. Minimal PR scope + +**No code in the RFC PR.** diff --git a/docs/rfc/RFC-0001-docker-plugin.md b/docs/rfc/RFC-0001-docker-plugin.md new file mode 100644 index 0000000..8da3b1c --- /dev/null +++ b/docs/rfc/RFC-0001-docker-plugin.md @@ -0,0 +1,83 @@ +# RFC-0001: Docker plugin + +**Status:** Proposed +**Author:** HomeBase DevShell maintainers +**Created:** 2026-06-29 +**Discussion:** *(open an Ideas discussion when ready)* + +--- + +## Summary + +Optional **Docker** plugin under `plugins/Docker/` that adds container-runtime readiness checks to `devshell health` — without new frozen CLI commands. + +## Motivation + +Developers on Windows often have broken Docker Desktop, WSL2 backend, or stale context while the rest of the workstation passes `devshell health`. Today that gap is invisible. + +Aligns with trust goal: **report what we can verify**, disclaim what we cannot (no image vulnerability scanning in v1). + +## User experience + +```powershell +devshell health # includes Docker section when plugin installed +devshell health -Json # plugin section in machine report +``` + +No `devshell docker` top-level command in v1 — health aggregation only. + +## Design + +### Scope + +**In** + +- Detect `docker` CLI on PATH +- Docker Desktop / engine reachable (`docker info` timeout-bounded) +- Optional: context name, WSL2 backend hint + +**Out** + +- Image CVE scanning +- Kubernetes / compose stack validation +- Auto-install Docker Desktop + +### Integration + +- `plugins/Docker/manifest.json` per [plugins/README.md](../../plugins/README.md) +- `doctor.ps1` invoked by health merger (post-acceptance design) +- JSON: new **optional** `sections.docker` object — additive only; schema minor bump if accepted + +### Security & trust + +- Read-only checks by default +- Any `repair.ps1` must be idempotent and documented; never pull arbitrary images +- Must pass MANIFESTO “no unverified software” rule + +## Alternatives considered + +| Option | Why not | +|--------|---------| +| Core built-in Docker checks | Violates v3.x “no core bloat”; Docker not universal | +| `devshell docker` command | Frozen API expansion — prefer health section | +| Ignore Docker | Leaves common dev pain unaddressed | + +## Drawbacks + +- Maintenance across Docker Desktop versions +- CI needs careful mocking (no Docker required on every runner) + +## Unresolved questions + +- [ ] Should plugin ship in main repo or separate repo first? +- [ ] Minimum checks for “PASS” vs “WARN”? +- [ ] Windows Home without Hyper-V — graceful INFO? + +## Implementation plan (after acceptance only) + +1. ADR: plugin manifest contract +2. RFC acceptance → `plugins/Docker/` skeleton + manifest only +3. Health merger + smoke test (mocked `docker`) +4. No release until [RELEASE-CRITERIA](../RELEASE-CRITERIA.md) green + +**Status: Proposed — no implementation code until Accepted.** diff --git a/docs/rfc/RFC-0002-wsl-plugin.md b/docs/rfc/RFC-0002-wsl-plugin.md new file mode 100644 index 0000000..d461458 --- /dev/null +++ b/docs/rfc/RFC-0002-wsl-plugin.md @@ -0,0 +1,85 @@ +# RFC-0002: WSL plugin + +**Status:** Proposed +**Author:** HomeBase DevShell maintainers +**Created:** 2026-06-29 +**Discussion:** *(open an Ideas discussion when ready)* + +--- + +## Summary + +Optional **WSL** plugin that reports Windows Subsystem for Linux readiness (distro installed, default version, integration with Docker backend) via `devshell health`. + +## Motivation + +WSL is a common dependency for Docker, Node, and Linux tooling on Windows. Failures are often silent until a tool fails mid-build. + +Supports the product goal: **trust through visible configuration state**, not promises about Linux workload performance. + +## User experience + +```powershell +devshell health +``` + +Example section (illustrative): + +``` +WSL WARN + Default: Ubuntu — WSL2 not default kernel +``` + +## Design + +### Scope + +**In** + +- `wsl --status` / `wsl -l -v` parsing (offline, local) +- Default distro present +- WSL version (1 vs 2) per distro +- Optional cross-check: Docker Desktop WSL integration flag (if Docker RFC accepted) + +**Out** + +- Installing distros or running `wsl --install` +- Linux package audits inside guest +- Network tests to external sites + +### Integration + +- `plugins/WSL/manifest.json` +- Health section `wslConfiguration` (name TBD at acceptance) +- Additive JSON only + +### Security & trust + +- No elevation required for read-only listing +- `repair.ps1` limited to documented safe actions (e.g. suggest `wsl --set-default-version 2`) — never force reboot + +## Alternatives considered + +| Option | Why not | +|--------|---------| +| Fold into Docker plugin only | WSL useful without Docker | +| Core doctor checks | Not all DevReady users use WSL — plugin keeps core small | + +## Drawbacks + +- Output varies by Windows build and locale +- Parsing `wsl` text is fragile — prefer structured flags where available + +## Unresolved questions + +- [ ] Minimum Windows build support? +- [ ] How to test in CI without WSL enabled on runner? +- [ ] Merge order with RFC-0001 (Docker)? + +## Implementation plan (after acceptance only) + +1. Accept RFC-0002 (may proceed in parallel with RFC-0001 if both Accepted) +2. Plugin skeleton + mocked unit tests +3. Document limitations in section disclaimer (like Privacy Configuration) + +**Status: Proposed — no implementation code until Accepted.** diff --git a/plugins/README.md b/plugins/README.md index 18b0242..fdb8515 100644 --- a/plugins/README.md +++ b/plugins/README.md @@ -2,6 +2,8 @@ HomeBase DevShell core stays small. Optional capabilities live in **plugins** without modifying frozen CLI commands. +**Before any plugin code:** propose and accept an [RFC](../docs/rfc/README.md) (e.g. [RFC-0001 Docker](../docs/rfc/RFC-0001-docker-plugin.md), [RFC-0002 WSL](../docs/rfc/RFC-0002-wsl-plugin.md)). + ## Planned layout ``` @@ -26,7 +28,7 @@ plugins/ } ``` -## Integration (not implemented in v3.0.0) +## Integration (not implemented until RFC Accepted) `devshell health` may merge plugin sections when `plugins/*/manifest.json` is present. Core health works **without** plugins.