From ba04a21268236602ac704e9ede86d1ebffb7d42d Mon Sep 17 00:00:00 2001 From: mniedre Date: Sun, 17 May 2026 14:45:12 +0300 Subject: [PATCH] =?UTF-8?q?feat(roadmap):=20add=20Phase=209=20=E2=80=94=20?= =?UTF-8?q?Documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new documentation phase covering README overhaul: motivation, install guide, use-case examples, tool comparison table, SSH/sudo prerequisite guides, troubleshooting, feedback section, and CI badges. Co-Authored-By: Claude Sonnet 4.6 --- .planning/ROADMAP.md | 17 +++++++++++++++++ .planning/STATE.md | 3 ++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 55ff259..3141ce8 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -20,6 +20,7 @@ Decimal phases appear between their surrounding integers in numeric order. - [ ] **Phase 6: Init Wizard** - `--init` creates target directory and writes deploy.yaml via root SSH - [ ] **Phase 7: v2 — Leftovers** - Expanded default excludes, `--skip-env` / `skip_env` setting, and `--verbose` flag - [ ] **Phase 8: Integration Tests** - Testcontainers-based suite verifies all requirements automatically against a real SSH daemon +- [ ] **Phase 9: Documentation** - README.md tells the full story: why, how to install, use-cases, comparison table, prerequisites, troubleshooting, and project badges ## Phase Details @@ -204,6 +205,21 @@ Cross-cutting constraints: 6. All preflight checks (CHECK-01 through CHECK-07) have at least one passing and one failing scenario covered 7. Health polling (HEALTH-01 through HEALTH-03) is exercised against a container with and without a HEALTHCHECK defined +### Phase 9: Documentation +**Goal**: README.md becomes the single authoritative resource for new users — explaining why the tool exists, how to install it, how to use it across all scenarios, and how to get help when things go wrong +**Depends on**: Phase 8 +**Plans**: TBD + +**Success Criteria** (what must be TRUE): + 1. README.md explains the core value proposition and motivation — why docker-deploy exists as a simpler alternative to complex CI/CD pipelines for developers who just want `scp + compose up` + 2. README.md includes a use-case section covering three scenarios: sshuser vs root, flags-only usage, and deploy.yaml config-driven usage with working examples + 3. README.md includes clear installation instructions covering binary download, plugin placement in `~/.docker/cli-plugins/`, and verification with `docker deploy --help` + 4. A comparison table of concurrent tools (Deployer, Kamal, Ansible, manual SSH scripts) is included with objective tradeoffs on complexity, dependencies, and target audience + 5. Prerequisite guide(s) cover SSH key setup and adding passwordless sudo to sshuser on the remote + 6. A troubleshooting section covers the most common failure scenarios (SSH auth failure, unknown host, writable dir, Docker not found, compose v1) with actionable fixes + 7. A feedback and suggestions section links to GitHub Issues with a welcome message for bug reports and feature requests + 8. README.md includes badges for build status, latest release version, and test status + ## Progress **Execution Order:** @@ -219,3 +235,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 | 6. Init Wizard | 0/? | Not started | - | | 7. v2 — Leftovers | 0/? | Not started | - | | 8. Integration Tests | 0/? | Not started | - | +| 9. Documentation | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 502cd31..222f9b9 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -7,7 +7,7 @@ stopped_at: Phase 5 complete — pre-flight checks and health polling verified a last_updated: "2026-05-17T06:10:00Z" last_activity: 2026-05-17 progress: - total_phases: 7 + total_phases: 9 completed_phases: 5 total_plans: 14 completed_plans: 14 @@ -88,6 +88,7 @@ Recent decisions affecting current work: - Phase 7 added: v2 — Leftovers (expanded default excludes, --skip-env / skip_env setting, --verbose flag) - Phase 7 edited: renamed from "Skip .env Override Option" to "Leftovers"; skip_env_override → skip_env; --verbose split into its own Wave 2 - Phase 8 added: Integration Tests (testcontainers-based suite verifying all requirements against real SSH daemon) +- Phase 9 added: Documentation (README.md — motivation, install, use-cases, comparison table, prerequisites, troubleshooting, badges, feedback section) ### Pending Todos