Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

docs(cloudformation): correct the resource-type contributor steps (#2762)

Hector Ventura54654760b5fd
diff --git a/AGENTS.md b/AGENTS.md
index b888a3685d..8ed8d1552f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -283,17 +283,36 @@ monolith being dismantled; new types go in per-service provisioners under
`local/aws/cfn-resource-schemas/us-east-1/` (`readOnlyProperties`), and validate
`required` from the same file.
4. **`provision` serves create *and* update.** On `UpdateStack` it is re-invoked with
- the prior physical id and attributes already populated on the resource. Branch on
- that instead of creating unconditionally.
-5. Override `delete(...)` when the type has a backing delete; tolerate already-deleted.
-6. Tests: focused unit test mocking one service (`SqsCfnProvisionerTest` is the
+ the prior physical id and attributes already populated on the resource. Branch with
+ `ctx.isUpdate()` / `ctx.priorPhysicalId()`, not by reading the id off the resource:
+ `provision` assigns the new id as it runs, so a resource-derived check flips
+ mid-method.
+5. Override `delete(...)` when the type has a backing delete; tolerate already-deleted
+ via `CfnDeletes.safeDelete`, passing the specific "already gone" error codes. Never
+ a catch-all: a real failure such as `BucketNotEmpty` must propagate so the stack
+ reports `DELETE_FAILED`. When the delete needs a create-time attribute rather than
+ just the physical id, override `delete(StackResource, String)`.
+6. **Register in `src/test/resources/cloudformation/supported-resource-types.tsv`**
+ (`type<TAB>Owner`). `CfnResourceInventoryTest` diffs that file against the
+ CDI-resolved registry, so it also catches a missing `@ApplicationScoped`.
+7. **Add the provisioner to `CfnProvisionerFixture.inferredProvisioners()`** when it
+ takes a single service, or a fixture test naming that service silently falls through
+ to the stub arm.
+8. Tests: focused unit test mocking one service (`SqsCfnProvisioner`'s test is the
pattern) plus an integration test asserting the **exact `Fn::GetAtt` keys**. An
unmapped type is stubbed as `CREATE_COMPLETE` with a fake ARN, so asserting status
- alone cannot detect a type that was never wired.
-7. Update the resource-type table in `docs/services/cloudformation.md`.
+ alone cannot detect a type that was never wired. Note the engine's constructor is
+ package-private, so tests in `provisioners/` mock it.
+9. Run `make docs-sync` and commit the result. The resource-type table in
+ `docs/services/cloudformation.md` is **generated** from the step-6 inventory; hand
+ edits fail `docs-check`. Labels, ordering and notes live in
+ `tools/docs/cfn_resource_types.yaml`.
+10. A schema `readOnlyProperties` entry you cannot set goes in
+ `src/test/resources/cloudformation/getatt-attribute-gaps.tsv` with a reason;
+ `CfnSchemaCoverageTest` requires every unset attribute to be fixed or recorded.
References: `SqsCfnProvisioner` (smallest), `Ec2LaunchTemplateCfnProvisioner`
-(update-in-place and replacement).
+(update-in-place and replacement), `LogsCfnProvisioner` (reconcile-vs-replace update).
---
@@ -387,6 +406,11 @@ Treat release workflows as critical infrastructure.
per-service provisioner
- Setting a CloudFormation resource's physical id but not its `Fn::GetAtt`
attributes (they are two separate mechanisms, and the miss is silent)
+- Hand-editing the resource-type table in `docs/services/cloudformation.md`, which is
+ generated, run `make docs-sync` instead
+- Adding a CloudFormation provisioner without a row in
+ `supported-resource-types.tsv` or an entry in `CfnProvisionerFixture`, either of
+ which leaves a type quietly served by the stub arm
---
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a3ebf2a487..5067931fbe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -168,19 +168,44 @@ otherwise create one.
`"LogicalId.Attr"`. Take the attribute names from the resource's registry schema under
`local/aws/cfn-resource-schemas/us-east-1/` (`readOnlyProperties`).
4. **`provision` is also the update path.** On `UpdateStack` it is called again with the previous
- physical id and attributes already set on the resource. Check for an existing physical id and
- update in place rather than creating unconditionally, which would otherwise throw
- `AlreadyExists` or orphan the old resource.
+ physical id and attributes already set on the resource. Use `ctx.isUpdate()` and
+ `ctx.priorPhysicalId()` rather than reading the id back off the resource: `provision` assigns the
+ new id as it works, so a resource-derived check changes meaning mid-method. Update in place
+ rather than creating unconditionally, which would otherwise throw `AlreadyExists` or orphan the
+ old resource.
5. Override `delete(...)` if the type has a backing delete. Deleting a resource that is already gone
- should be tolerated.
-6. Add a focused unit test (mock only your service, see `SqsCfnProvisionerTest`) and an integration
- test. Assert the **specific `Fn::GetAtt` attribute keys**, not just `CREATE_COMPLETE`: an
- unmapped type is stubbed out as a successful no-op, so a status-only assertion passes even when
- nothing was provisioned.
-7. Add the type to the table in `docs/services/cloudformation.md`.
+ should be tolerated: `CfnDeletes.safeDelete` does this, taking the specific error codes that
+ mean "already gone" (never a catch-all: a real failure such as `BucketNotEmpty` must propagate so
+ the stack reports `DELETE_FAILED`).
+ If the delete needs more than the physical id (a create-time attribute such as a rule's event
+ bus), override `delete(StackResource, String)` instead, which receives the whole resource.
+6. **Register the type in `src/test/resources/cloudformation/supported-resource-types.tsv`**
+ (`type<TAB>YourCfnProvisioner`). `CfnResourceInventoryTest` compares that file against the
+ CDI-resolved registry, so it fails if you forget, which is also what catches a missing
+ `@ApplicationScoped`.
+7. **Make your provisioner reachable from `CfnProvisionerFixture`** if it takes a single service.
+ That is three edits, not one: a `private <Svc>Service` field on `Builder`, a
+ `public Builder <svc>(<Svc>Service v)` setter for it, and a construction arm in
+ `inferredProvisioners()`. Tests name a service and the fixture wires the matching provisioner;
+ without all three, a test exercising your type silently falls through to the stub arm instead.
+ The setter is the step that gets missed: a field nothing can assign stays null, so its
+ construction arm never runs. `CfnProvisionerFixtureTest` fails if the provisioner cannot be
+ reached through the public builder.
+8. Add a focused unit test (mock only your service, see `SqsCfnProvisioner`'s test) and an
+ integration test. Assert the **specific `Fn::GetAtt` attribute keys**, not just
+ `CREATE_COMPLETE`: an unmapped type is stubbed out as a successful no-op, so a status-only
+ assertion passes even when nothing was provisioned.
+9. Run `make docs-sync` to regenerate the resource-type table in `docs/services/cloudformation.md`,
+ and commit the result. **Do not hand-edit that table**: it is generated from the inventory in
+ step 6. Presentation (service label, ordering, notes) lives in `tools/docs/cfn_resource_types.yaml`.
+10. If your type has a schema `readOnlyProperties` entry you cannot set, add a row to
+ `src/test/resources/cloudformation/getatt-attribute-gaps.tsv` with the reason.
+ `CfnSchemaCoverageTest` requires every unset attribute to be either fixed or recorded, so
+ "not emulated" stays distinguishable from "forgotten".
`SqsCfnProvisioner` is the smallest reference implementation; `Ec2LaunchTemplateCfnProvisioner`
-shows update-in-place and replacement handling.
+shows update-in-place and replacement handling; `LogsCfnProvisioner` shows a full reconcile-vs-replace
+update path.
## Pull Request Guidelines