add instructions for breaking change introduced in #22610

website/docs/guides/version-4-upgrade.html.md

@@ -689,6 +689,60 @@ To help distribute the management of S3 bucket settings via independent resource
 have become read-only. Configurations dependent on these arguments should be updated to use the corresponding `aws_s3_bucket_*` resource.
 Once updated, new `aws_s3_bucket_*` resources should be imported into Terraform state.
 
+### `acceleration_status` Argument deprecation
+
+Switch your Terraform configuration to the `aws_s3_bucket_accelerate_configuration` resource instead.
+
+For example, given this previous configuration:
+
+```terraform
+resource "aws_s3_bucket" "example" {
+  # ... other configuration ...
+  acceleration_status = "Enabled"
+}
+```
+
+It will receive the following error after upgrading:
+
+```
+│ Error: Value for unconfigurable attribute
+│
+│   with aws_s3_bucket.example,
+│   on main.tf line 1, in resource "aws_s3_bucket" "example":
+│    1: resource "aws_s3_bucket" "example" {
+│
+│ Can't configure a value for "acceleration_status": its value will be decided automatically based on the result of applying this configuration.
+```
+
+Since the `acceleration_status` argument changed to read-only, the recommendation is to update the configuration to use the `aws_s3_bucket_accelerate_configuration`
+resource and remove any reference to `acceleration_status` in the `aws_s3_bucket` resource:
+
+```terraform
+resource "aws_s3_bucket" "example" {
+  # ... other configuration ...
+}
+
+resource "aws_s3_bucket_accelerate_configuration" "example" {
+  bucket = aws_s3_bucket.example.id
+  status = "Enabled"
+}
+```
+
+It is then recommended running `terraform import` on each new resource to prevent data loss, e.g.
+
+```shell
+$ terraform import aws_s3_bucket_accelerate_configuration.example example
+aws_s3_bucket_accelerate_configuration.example: Importing from ID "example"...
+aws_s3_bucket_accelerate_configuration.example: Import prepared!
+  Prepared aws_s3_bucket_accelerate_configuration for import
+aws_s3_bucket_accelerate_configuration.example: Refreshing state... [id=example]
+
+Import successful!
+
+The resources that were imported are shown above. These resources are now in
+your Terraform state and will henceforth be managed by Terraform.
+```
+
 ### `cors_rule` Argument deprecation
 
 Switch your Terraform configuration to the `aws_s3_bucket_cors_configuration` resource instead.