From ae29bb5bceaf3cb65c2adbaeaac13bbac32d186d Mon Sep 17 00:00:00 2001
From: Xia Zhao <78883180+xazhao@users.noreply.github.com>
Date: Tue, 5 Nov 2024 00:05:18 -0800
Subject: [PATCH] chore(s3): add more details to prune and destinationKeyPrefix
 property (#32011)

### Reason for this change
`prune` and `destinationKeyPrefix` properties documentation is not super clear for users. Adding more details to behaviors when setting/unsetting the property.

### Description of changes



### Description of how you validated changes



### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 .../aws-s3-deployment/lib/bucket-deployment.ts         | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts b/packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts
index d10bfb249fed0..cd32d6017be51 100644
--- a/packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts
+++ b/packages/aws-cdk-lib/aws-s3-deployment/lib/bucket-deployment.ts
@@ -32,9 +32,12 @@ export interface BucketDeploymentProps {
   readonly destinationBucket: s3.IBucket;
 
   /**
-   * Key prefix in the destination bucket.
+   * Key prefix in the destination bucket. Must be <=104 characters
    *
-   * Must be <=104 characters
+   * If it's set with prune: true, it will only prune files with the prefix.
+   *
+   * We recommend to always configure the `destinationKeyPrefix` property. This will prevent the deployment
+   * from accidentally deleting data that wasn't uploaded by it.
    *
    * @default "/" (unzip to root of the destination bucket)
    */
@@ -71,6 +74,9 @@ export interface BucketDeploymentProps {
   readonly include?: string[];
 
   /**
+   * By default, files in the destination bucket that don't exist in the source will be deleted
+   * when the BucketDeployment resource is created or updated.
+   *
    * If this is set to false, files in the destination bucket that
    * do not exist in the asset, will NOT be deleted during deployment (create/update).
    *