chore(app-staging-synthesizer): document and test autoDeleteStagingAssets: false

packages/@aws-cdk/app-staging-synthesizer-alpha/README.md

@@ -249,6 +249,22 @@ const app = new App({
 });
 ```
 
+### Auto Delete Staging Assets on Deletion
+
+By default, the staging resources will be cleaned up on stack deletion. That means that the
+S3 Bucket and ECR Repositories are set to `RemovalPolicy.DESTROY` and have `autoDeleteObjects`
+or `autoDeleteImages` turned on. This creates custom resources under the hood to facilitate
+cleanup. To turn this off, specify `autoDeleteStagingAssets: false`.
+
+```ts
+const app = new App({
+  defaultStackSynthesizer: AppStagingSynthesizer.defaultResources({
+    appId: 'my-app-id',
+    autoDeleteStagingAssets: false,
+  }),
+});
+```
+
 ## Using a Custom Staging Stack per Environment
 
 If you want to customize some behavior that is not configurable via properties,

packages/@aws-cdk/app-staging-synthesizer-alpha/test/app-staging-synthesizer.test.ts

@@ -462,6 +462,36 @@ describe(AppStagingSynthesizer, () => {
     });
   });
 
+  test('auto delete assets can be turned off', () => {
+    // GIVEN
+    app = new App({
+      defaultStackSynthesizer: AppStagingSynthesizer.defaultResources({
+        appId: APP_ID,
+        autoDeleteStagingAssets: false,
+      }),
+    });
+    stack = new Stack(app, 'Stack', {
+      env: {
+        account: '000000000000',
+        region: 'us-east-1',
+      },
+    });
+
+    const assetName = 'abcdef';
+    stack.synthesizer.addDockerImageAsset({
+      directoryName: '.',
+      sourceHash: 'abcdef',
+      assetName,
+    });
+
+    // WHEN
+    const asm = app.synth();
+
+    // THEN
+    Template.fromJSON(getStagingResourceStack(asm).template).resourceCountIs('Custom::ECRAutoDeleteImages', 0);
+    Template.fromJSON(getStagingResourceStack(asm).template).resourceCountIs('Custom::S3AutoDeleteObjects', 0);
+  });
+
   describe('environment specifics', () => {
     test('throws if App includes env-agnostic and specific env stacks', () => {
       // GIVEN - App with Stack with specific environment