From 1eac78fa86cb7b67b3d56e9ae88a71dd21bee956 Mon Sep 17 00:00:00 2001 From: Sung-Kyu Yoo Date: Sat, 18 Jul 2026 11:04:13 +0900 Subject: [PATCH 1/3] docs: sync roadmap with actual codebase state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The roadmap described "6 implemented services" and a "prove the thesis on AWS" Phase 1 premise that is long past — the repo has 101 services (`make stats`) with deep coverage, working cross-service integrations, and a plugin system. - Reframe Phase 1 as "AWS Depth & Stabilization" with accurate checkboxes (stub reduction, compat edge cases, stable ServicePlugin API remain open) - Mark 0.x as the current version line in the version-mapping table - De-rot volatile numbers: point at `make test-compat` instead of the stale 671/699 count; fix every "96 services" -> 101 across README and docs Phases 2-4 (multi-CSP prep, Azure pilot, breadth) left intact. Docs-only; no changie fragment (matches prior docs-sync PR #52). --- README.md | 4 ++-- docs/README.md | 2 +- docs/configuration.md | 2 +- docs/faq.md | 4 ++-- docs/roadmap.md | 22 ++++++++++++---------- docs/services-matrix.md | 2 +- 6 files changed, 19 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 936eab38..87b2de72 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Today DevCloud targets **AWS**. Our long-term goal is to support the full range ## Features - **101 AWS services scaffolded** — 4,451 operations across all major categories (run `make stats` to verify; see [services-matrix.md](docs/services-matrix.md)) -- **96% boto3 compatibility** — 671/699 SDK tests pass; works with most boto3 apps +- **~96% boto3 compatibility** — run `make test-compat` for the current pass rate; works with most boto3 apps - **Cross-service integration** — CFN provisioning, DDB Streams → Lambda, EventBridge targets, S3 → Lambda - **Smithy-driven codegen** — auto-generate Go interfaces, types, and serializers from Smithy models - **Weekly auto-sync** — GitHub Actions keeps generated code up to date with upstream AWS API changes @@ -60,7 +60,7 @@ Start at the [docs index](docs/) for the full map. Quick links: - [Getting Started](docs/getting-started.md) — Installation, first use, boto3 / AWS CLI / Terraform examples - [Configuration](docs/configuration.md) — Config options, env-var overrides, tier shortcuts - [Architecture](docs/architecture.md) — System design, codegen pipeline, plugin model, multi-CSP vision -- [Services Matrix](docs/services-matrix.md) — 96 services, coverage status, boto3 pass rate +- [Services Matrix](docs/services-matrix.md) — 101 services, coverage status, boto3 pass rate - [Roadmap](docs/roadmap.md) — Phased plan toward multi-CSP support - [FAQ](docs/faq.md) / [Troubleshooting](docs/troubleshooting.md) — Common questions and errors - [Contributing](docs/contributing.md) — Development setup, adding new services diff --git a/docs/README.md b/docs/README.md index ac6ff33b..98f0dad8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ This directory holds DevCloud's technical documentation. Use the map below to ju - **[Configuration](configuration.md)** — YAML options, env-var overrides, tier shortcuts - **[Architecture](architecture.md)** — system design, plugin model, codegen pipeline, multi-CSP vision - **[Roadmap](roadmap.md)** — phased plan toward multi-CSP support -- **[Services Matrix](services-matrix.md)** — 96 services, coverage status, boto3 pass rate +- **[Services Matrix](services-matrix.md)** — 101 services, coverage status, boto3 pass rate ## Per-service references diff --git a/docs/configuration.md b/docs/configuration.md index a016a557..e3dee970 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration -**Configuration is optional.** DevCloud ships with built-in defaults: running `devcloud` with no flags enables all 96 services on port 4747, storing data under `./data//`. The embedded defaults are compiled into the binary from [`internal/config/default.yaml`](https://github.com/skyoo2003/devcloud/blob/main/internal/config/default.yaml). +**Configuration is optional.** DevCloud ships with built-in defaults: running `devcloud` with no flags enables all 101 services on port 4747, storing data under `./data//`. The embedded defaults are compiled into the binary from [`internal/config/default.yaml`](https://github.com/skyoo2003/devcloud/blob/main/internal/config/default.yaml). To override defaults, provide a YAML file. DevCloud looks for config in this order: diff --git a/docs/faq.md b/docs/faq.md index a58640b7..6762e369 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,7 +15,7 @@ No. DevCloud is a local development tool. It is **not** designed or tested for p DevCloud positions itself as an **on-ramp** rather than a replacement. Key differentiators: - **Go-based single binary** — starts in under a second, no JVM or Python runtime. -- **Smithy-driven codegen** — 96 AWS services scaffolded from official models, weekly auto-sync. +- **Smithy-driven codegen** — 101 AWS services scaffolded from official models, weekly auto-sync. - **Multi-CSP vision** — AWS today, Azure and GCP planned; see [roadmap.md](roadmap.md). - **Apache 2.0 licensed** with explicit patent grant. @@ -29,7 +29,7 @@ Developers should be able to iterate locally without cloud bills and deploy to t ### Which services are supported? -96 AWS services are scaffolded and routed; coverage depth varies. See [services-matrix.md](services-matrix.md) for the canonical list and per-service operation counts. Core services (S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, SecretsManager, EventBridge, CloudFormation) pass 100% of their boto3 compatibility tests. +101 AWS services are scaffolded and routed; coverage depth varies. See [services-matrix.md](services-matrix.md) for the canonical list and per-service operation counts. Core services (S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, SecretsManager, EventBridge, CloudFormation) pass 100% of their boto3 compatibility tests. ### Does DevCloud work on Windows? diff --git a/docs/roadmap.md b/docs/roadmap.md index 8c43f07c..1a64344b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -14,17 +14,19 @@ We pursue this vision through a **phased rollout** to manage scope, architectura ## Phases -### Phase 1 — AWS Depth (Current, targeting v1.0) +### Phase 1 — AWS Depth & Stabilization (Current, targeting v1.0) -**Goal**: prove the core thesis on AWS before expanding surface area. +**Goal**: mature the already-broad AWS surface into a stable, well-tested v1.0. -- [x] Core AWS services: S3, SQS, DynamoDB, Lambda, IAM, STS -- [x] Smithy-based codegen pipeline (run `make stats` for current counts) -- [x] Cross-service integration (CFN, DDB Streams → Lambda, EventBridge, S3 → Lambda) -- [x] boto3 compatibility suite (currently 671/699 passing) -- [ ] Lift boto3 compatibility to ≥ 95% -- [ ] Deepen coverage on existing 6 implemented services (fewer `NotImplementedError` returns) -- [ ] v1.0 release with stable plugin API +- [x] 100+ AWS services scaffolded from official Smithy models via in-tree codegen (run `make stats` for current counts) +- [x] Deep hand-written coverage on core + integration + extended services (see [services-matrix.md](services-matrix.md) for the per-tier breakdown) +- [x] Cross-service integration (CloudFormation, DynamoDB Streams → Lambda, SQS → Lambda, S3 → Lambda, EventBridge, SNS → SQS) +- [x] boto3 compatibility suite (`make test-compat`); core services — S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation — pass 100% +- [x] boto3 compatibility ≥ 95% overall (currently ~96%; run `make test-compat`) +- [ ] Reduce `NotImplementedError` across scaffolded "Category Expansion" services (fewer stub operations) +- [ ] Close remaining compatibility edge cases (S3Tables ARN path parsing, ServerlessRepo restJson1 `jsonName`, Textract/Support endpoints) +- [ ] Finalize and document a stable `ServicePlugin` API (`internal/plugin/`) +- [ ] v1.0 release ### Phase 2 — Architectural Preparation (v1.x) @@ -72,7 +74,7 @@ We pursue this vision through a **phased rollout** to manage scope, architectura | Version | Focus | |---------|-------| -| 0.x | AWS services, unstable API | +| 0.x ← current | AWS services, unstable API | | 1.x | AWS depth, stable plugin API | | 2.x | Multi-CSP architecture, Azure pilot | | 3.x+ | Broad CSP coverage, community-owned providers | diff --git a/docs/services-matrix.md b/docs/services-matrix.md index 870d7e3e..001fa9f0 100644 --- a/docs/services-matrix.md +++ b/docs/services-matrix.md @@ -62,7 +62,7 @@ DevCloud is a Go-based local cloud environment with AWS API compatibility. This ## boto3 compatibility - Tests: `tests/compatibility/` -- Pass rate: **671/699 (96%)** +- Pass rate: **~96%** (run `make test-compat` for the current count) - Run: `make test-compat` Remaining 28 failures are concentrated in edge cases of newly-added services From 16dc52f77389e881a3c4bd1d1c8ab87c66569ed5 Mon Sep 17 00:00:00 2001 From: Sung-Kyu Yoo Date: Sat, 18 Jul 2026 11:07:36 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20fix?= =?UTF-8?q?=20Secrets=20Manager=20naming,=20reduce=20rot-prone=20wording?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Spell "Secrets Manager" (was "SecretsManager") in faq.md and services-matrix.md, matching AWS's name and the roadmap bullet - Roadmap: drop redundant "~96%" from the ≥95% checkbox (the checkbox already asserts the milestone) and generalize the named edge-case bug list, which would go stale as those bugs are fixed - faq.md: tie the ~96% figure to `make test-compat` so it reads as a refreshable snapshot --- docs/faq.md | 4 ++-- docs/roadmap.md | 4 ++-- docs/services-matrix.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 6762e369..062beb25 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -29,7 +29,7 @@ Developers should be able to iterate locally without cloud bills and deploy to t ### Which services are supported? -101 AWS services are scaffolded and routed; coverage depth varies. See [services-matrix.md](services-matrix.md) for the canonical list and per-service operation counts. Core services (S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, SecretsManager, EventBridge, CloudFormation) pass 100% of their boto3 compatibility tests. +101 AWS services are scaffolded and routed; coverage depth varies. See [services-matrix.md](services-matrix.md) for the canonical list and per-service operation counts. Core services (S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation) pass 100% of their boto3 compatibility tests. ### Does DevCloud work on Windows? @@ -49,7 +49,7 @@ See [configuration.md](configuration.md) for data directory options. ### Will my existing boto3 code work? -96% of boto3's official SDK test suite passes against DevCloud. Most apps that use the Big 6 (S3, SQS, DynamoDB, Lambda, IAM, STS) and common integration services (SNS, CloudWatch, KMS, SecretsManager, EventBridge, CloudFormation) will work with only an `endpoint_url` change. +~96% of boto3's official SDK test suite passes against DevCloud (run `make test-compat` for the current rate). Most apps that use the Big 6 (S3, SQS, DynamoDB, Lambda, IAM, STS) and common integration services (SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation) will work with only an `endpoint_url` change. ### What about Terraform / CDK? diff --git a/docs/roadmap.md b/docs/roadmap.md index 1a64344b..37a73102 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -22,9 +22,9 @@ We pursue this vision through a **phased rollout** to manage scope, architectura - [x] Deep hand-written coverage on core + integration + extended services (see [services-matrix.md](services-matrix.md) for the per-tier breakdown) - [x] Cross-service integration (CloudFormation, DynamoDB Streams → Lambda, SQS → Lambda, S3 → Lambda, EventBridge, SNS → SQS) - [x] boto3 compatibility suite (`make test-compat`); core services — S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation — pass 100% -- [x] boto3 compatibility ≥ 95% overall (currently ~96%; run `make test-compat`) +- [x] boto3 compatibility ≥ 95% overall (run `make test-compat` for the current rate) - [ ] Reduce `NotImplementedError` across scaffolded "Category Expansion" services (fewer stub operations) -- [ ] Close remaining compatibility edge cases (S3Tables ARN path parsing, ServerlessRepo restJson1 `jsonName`, Textract/Support endpoints) +- [ ] Close remaining boto3 compatibility edge cases in newly-added services - [ ] Finalize and document a stable `ServicePlugin` API (`internal/plugin/`) - [ ] v1.0 release diff --git a/docs/services-matrix.md b/docs/services-matrix.md index 001fa9f0..541e9391 100644 --- a/docs/services-matrix.md +++ b/docs/services-matrix.md @@ -68,7 +68,7 @@ DevCloud is a Go-based local cloud environment with AWS API compatibility. This Remaining 28 failures are concentrated in edge cases of newly-added services (ARN path parsing in S3Tables, restJson1 jsonName in ServerlessRepo, specialized Textract/Support endpoints). Core services (S3, SQS, DynamoDB, Lambda, IAM, STS, -SNS, CloudWatch, KMS, SecretsManager, EventBridge, CloudFormation) all pass +SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation) all pass 100% of their tests. ## Supported protocols From 51fc9dd9847432501408ea4ca483b5b461978b3c Mon Sep 17 00:00:00 2001 From: Sung-Kyu Yoo Date: Sat, 18 Jul 2026 14:27:35 +0900 Subject: [PATCH 3/3] docs: finish de-rotting counts flagged by review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Earlier pass softened some numbers but left contradicting hard-coded ones: - services-matrix.md header: 4,451 -> 4,460 (matches `make stats`), 96% -> ~96% (matches the softened pass-rate line below it); refresh note now points at `make test-compat` for the compat figure, not just `make stats` - services-matrix.md: drop the exact "28 failures" count (contradicted ~96%) - README.md: state operations as a "4,400+" floor so it can't drift - roadmap.md: don't mark all extended-tier coverage done — claim core + integration + *major* extended, and scope stub reduction to less-common operations plus scaffolded services --- README.md | 2 +- docs/roadmap.md | 4 ++-- docs/services-matrix.md | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 87b2de72..d4ef9479 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Today DevCloud targets **AWS**. Our long-term goal is to support the full range ## Features -- **101 AWS services scaffolded** — 4,451 operations across all major categories (run `make stats` to verify; see [services-matrix.md](docs/services-matrix.md)) +- **101 AWS services scaffolded** — 4,400+ operations across all major categories (run `make stats` for current counts; see [services-matrix.md](docs/services-matrix.md)) - **~96% boto3 compatibility** — run `make test-compat` for the current pass rate; works with most boto3 apps - **Cross-service integration** — CFN provisioning, DDB Streams → Lambda, EventBridge targets, S3 → Lambda - **Smithy-driven codegen** — auto-generate Go interfaces, types, and serializers from Smithy models diff --git a/docs/roadmap.md b/docs/roadmap.md index 37a73102..6871a4b2 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -19,11 +19,11 @@ We pursue this vision through a **phased rollout** to manage scope, architectura **Goal**: mature the already-broad AWS surface into a stable, well-tested v1.0. - [x] 100+ AWS services scaffolded from official Smithy models via in-tree codegen (run `make stats` for current counts) -- [x] Deep hand-written coverage on core + integration + extended services (see [services-matrix.md](services-matrix.md) for the per-tier breakdown) +- [x] Deep hand-written coverage on core, integration, and major extended services (see [services-matrix.md](services-matrix.md) for per-tier depth) - [x] Cross-service integration (CloudFormation, DynamoDB Streams → Lambda, SQS → Lambda, S3 → Lambda, EventBridge, SNS → SQS) - [x] boto3 compatibility suite (`make test-compat`); core services — S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation — pass 100% - [x] boto3 compatibility ≥ 95% overall (run `make test-compat` for the current rate) -- [ ] Reduce `NotImplementedError` across scaffolded "Category Expansion" services (fewer stub operations) +- [ ] Reduce remaining `NotImplementedError` stubs (less-common operations and scaffolded "Category Expansion" services) - [ ] Close remaining boto3 compatibility edge cases in newly-added services - [ ] Finalize and document a stable `ServicePlugin` API (`internal/plugin/`) - [ ] v1.0 release diff --git a/docs/services-matrix.md b/docs/services-matrix.md index 541e9391..68328faa 100644 --- a/docs/services-matrix.md +++ b/docs/services-matrix.md @@ -1,8 +1,8 @@ # DevCloud Services Matrix -**Total**: 101 services, 4,451 operations, 96% boto3 compatibility +**Total**: 101 services, 4,460 operations, ~96% boto3 compatibility -> To refresh these numbers, run `make stats` and update the line above. +> To refresh these numbers, run `make stats` (services/operations) and `make test-compat` (compatibility), then update the line above. _Last updated with each release. For unreleased changes, see [CHANGELOG.md](../CHANGELOG.md)._ @@ -65,7 +65,7 @@ DevCloud is a Go-based local cloud environment with AWS API compatibility. This - Pass rate: **~96%** (run `make test-compat` for the current count) - Run: `make test-compat` -Remaining 28 failures are concentrated in edge cases of newly-added services +Remaining failures are concentrated in edge cases of newly-added services (ARN path parsing in S3Tables, restJson1 jsonName in ServerlessRepo, specialized Textract/Support endpoints). Core services (S3, SQS, DynamoDB, Lambda, IAM, STS, SNS, CloudWatch, KMS, Secrets Manager, EventBridge, CloudFormation) all pass