From 3b523498fccf72811c6f249b6553a75f4a954ef3 Mon Sep 17 00:00:00 2001 From: Julian Sommer <115516918+juliansommer@users.noreply.github.com> Date: Tue, 15 Sep 2026 10:56:29 +1000 Subject: [PATCH] docs: stop publishing planned RDS work as never Multi-AZ clusters, read replicas and point-in-time restore were declared not applicable, which says the platform will never serve them. All three are planned, so the pages claimed something the roadmap contradicts. Only a declaration now publishes that claim. A handler that refuses an operation today establishes nothing about tomorrow, so it reads as the gap it is rather than a permanent one. --- docs/coverage/pages.json | 15 ++------------- docs/coverage/rds/README.md | 21 +++++---------------- internal/awsmodel/page.go | 9 ++++++--- internal/awsmodel/page_test.go | 12 ++++++------ 4 files changed, 19 insertions(+), 38 deletions(-) diff --git a/docs/coverage/pages.json b/docs/coverage/pages.json index 726ac4f0f..e9d1a045c 100644 --- a/docs/coverage/pages.json +++ b/docs/coverage/pages.json @@ -202,24 +202,13 @@ "SubmitDBStateChange" ], "notApplicable": { - "CreateDBCluster": "clusters", - "CreateDBInstanceReadReplica": "read-replicas", "CreateOptionGroup": "option-groups", - "DeleteDBCluster": "clusters", "DeleteOptionGroup": "option-groups", - "DescribeDBClusters": "clusters", "DescribeOptionGroups": "option-groups", - "FailoverDBCluster": "clusters", - "ModifyDBCluster": "clusters", - "ModifyOptionGroup": "option-groups", - "PromoteReadReplica": "read-replicas", - "RestoreDBInstanceToPointInTime": "point-in-time-restore" + "ModifyOptionGroup": "option-groups" }, "notes": { - "clusters": "Aurora and Multi-AZ clusters are not offered; a DB instance here is a single VM running the engine directly.", - "option-groups": "Option groups configure engine add-ons for engines this platform does not offer, such as Oracle and SQL Server.", - "point-in-time-restore": "Point-in-time restore needs continuous transaction-log archival, which the backup path does not keep.", - "read-replicas": "Replication between instances is not offered, so there is no replica to create or promote." + "option-groups": "Option groups configure engine add-ons for engines this platform does not offer, such as Oracle and SQL Server." } }, "s3": { diff --git a/docs/coverage/rds/README.md b/docs/coverage/rds/README.md index 1df466ff5..db7cbb7a4 100644 --- a/docs/coverage/rds/README.md +++ b/docs/coverage/rds/README.md @@ -73,20 +73,16 @@ A parameter whose omission would create a false safety, security or availability | Operation | Status | |---|---| | `AddTagsToResource` | ✅ Implemented | -| `CreateDBCluster` | ⛔ Not applicable [1](#notes) | | `CreateDBInstance` | ✅ Implemented | -| `CreateDBInstanceReadReplica` | ⛔ Not applicable [4](#notes) | | `CreateDBParameterGroup` | ✅ Implemented | | `CreateDBSnapshot` | ✅ Implemented | | `CreateDBSubnetGroup` | ✅ Implemented | -| `CreateOptionGroup` | ⛔ Not applicable [2](#notes) | -| `DeleteDBCluster` | ⛔ Not applicable [1](#notes) | +| `CreateOptionGroup` | ⛔ Not applicable [1](#notes) | | `DeleteDBInstance` | ✅ Implemented | | `DeleteDBParameterGroup` | ✅ Implemented | | `DeleteDBSnapshot` | ✅ Implemented | | `DeleteDBSubnetGroup` | ✅ Implemented | -| `DeleteOptionGroup` | ⛔ Not applicable [2](#notes) | -| `DescribeDBClusters` | ⛔ Not applicable [1](#notes) | +| `DeleteOptionGroup` | ⛔ Not applicable [1](#notes) | | `DescribeDBEngineVersions` | ✅ Implemented | | `DescribeDBInstanceAutomatedBackups` | ✅ Implemented | | `DescribeDBInstances` | ✅ Implemented | @@ -95,25 +91,18 @@ A parameter whose omission would create a false safety, security or availability | `DescribeDBSnapshots` | ✅ Implemented | | `DescribeDBSubnetGroups` | ✅ Implemented | | `DescribeEvents` | ✅ Implemented | -| `DescribeOptionGroups` | ⛔ Not applicable [2](#notes) | +| `DescribeOptionGroups` | ⛔ Not applicable [1](#notes) | | `DescribeOrderableDBInstanceOptions` | ✅ Implemented | -| `FailoverDBCluster` | ⛔ Not applicable [1](#notes) | | `ListTagsForResource` | ✅ Implemented | -| `ModifyDBCluster` | ⛔ Not applicable [1](#notes) | | `ModifyDBInstance` | ✅ Implemented | | `ModifyDBParameterGroup` | ✅ Implemented | -| `ModifyOptionGroup` | ⛔ Not applicable [2](#notes) | -| `PromoteReadReplica` | ⛔ Not applicable [4](#notes) | +| `ModifyOptionGroup` | ⛔ Not applicable [1](#notes) | | `RebootDBInstance` | ✅ Implemented | | `RemoveTagsFromResource` | ✅ Implemented | | `RestoreDBInstanceFromDBSnapshot` | ✅ Implemented | -| `RestoreDBInstanceToPointInTime` | ⛔ Not applicable [3](#notes) | | `StartDBInstance` | ✅ Implemented | | `StopDBInstance` | ✅ Implemented | ### Notes -1. Aurora and Multi-AZ clusters are not offered; a DB instance here is a single VM running the engine directly. -2. Option groups configure engine add-ons for engines this platform does not offer, such as Oracle and SQL Server. -3. Point-in-time restore needs continuous transaction-log archival, which the backup path does not keep. -4. Replication between instances is not offered, so there is no replica to create or promote. +1. Option groups configure engine add-ons for engines this platform does not offer, such as Oracle and SQL Server. diff --git a/internal/awsmodel/page.go b/internal/awsmodel/page.go index 3a539c5b6..555e58adc 100644 --- a/internal/awsmodel/page.go +++ b/internal/awsmodel/page.go @@ -54,8 +54,9 @@ func (c OperationCoverage) ImplementedPercent() float64 { // less the internal routes the page declares. // // The page's NotApplicable declares operations the platform will never serve, -// mapped to the note key explaining why. A refusing handler is the same fact -// reached mechanically, so both publish as StatusNotApplicable. +// mapped to the note key explaining why, and is the only thing that publishes +// that claim. A handler that refuses today may be implemented tomorrow, so a +// refusal on its own is a gap like any other rather than a "never". func (c OperationCoverage) OperationStatuses(page PageMetadata) ([]OperationStatus, error) { registered := toSet(c.Registered) stubbed := toSet(c.Stubbed) @@ -89,8 +90,10 @@ func (c OperationCoverage) OperationStatuses(page PageMetadata) ([]OperationStat switch { case stubbed[operation]: status = StatusStub + // A registered handler that refuses serves nothing, so it reads as the + // gap it is unless the page declares why it is permanent. case unsupported[operation]: - status = StatusNotApplicable + status = StatusNotImplemented case registered[operation]: status = StatusImplemented } diff --git a/internal/awsmodel/page_test.go b/internal/awsmodel/page_test.go index 44fab325f..ef11d2e4d 100644 --- a/internal/awsmodel/page_test.go +++ b/internal/awsmodel/page_test.go @@ -90,7 +90,6 @@ func TestRenderServicePageCarriesEveryPublishedStatus(t *testing.T) { "| `AssumeRole` | " + StatusImplemented + " |", "| `GetSessionToken` | " + StatusStub + " |", "| `PublishInternal` | " + StatusOutsideModel + " |", - "| `GetCallerIdentity` | " + StatusNotApplicable + " |", } { if !strings.Contains(page, want) { t.Errorf("page does not contain %q:\n%s", want, page) @@ -289,9 +288,10 @@ func TestRenderServicePageFootnotesSharedNotes(t *testing.T) { } } -// A refusal the dispatch tables report is published as a row whether or not the -// page declares a reason for it. -func TestRenderServicePageRowsAnUndeclaredRefusal(t *testing.T) { +// "Not applicable" says the platform will never serve an operation, which a +// handler refusing it today does not establish. Only the page's declaration +// publishes that claim; an undeclared refusal is a gap like any other. +func TestRenderServicePageDoesNotPublishAnUndeclaredRefusalAsPermanent(t *testing.T) { pages := testPageSet(t) coverage, err := CompareOperations(STS, DispatchInventory{ Registered: []string{"AssumeRole", "GetFederationToken"}, @@ -305,8 +305,8 @@ func TestRenderServicePageRowsAnUndeclaredRefusal(t *testing.T) { if err != nil { t.Fatal(err) } - if !strings.Contains(page, "| `GetFederationToken` | "+StatusNotApplicable+" |") { - t.Errorf("an undeclared refusal is not published:\n%s", page) + if strings.Contains(page, "| `GetFederationToken` |") { + t.Errorf("an undeclared refusal is published as a permanent claim:\n%s", page) } }