add instructions for breaking change introduced in #22599

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

@@ -810,6 +810,74 @@ The resources that were imported are shown above. These resources are now in
 your Terraform state and will henceforth be managed by Terraform.
 ```
 
+### `logging` Argument deprecation
+
+Switch your Terraform configuration to the `aws_s3_bucket_logging` resource instead.
+
+For example, given this previous configuration:
+
+```terraform
+resource "aws_s3_bucket" "log_bucket" {
+  # ... other configuration ...
+  bucket = "example-log-bucket"
+}
+
+resource "aws_s3_bucket" "example" {
+  # ... other configuration ...
+  logging {
+    target_bucket = aws_s3_bucket.log_bucket.id
+    target_prefix = "log/"
+  }
+}
+```
+
+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 "logging": its value will be decided automatically based on the result of applying this configuration.
+```
+
+Since the `logging` argument changed to read-only, the recommendation is to update the configuration to use the `aws_s3_bucket_logging`
+resource and remove any references to `logging` and its nested arguments in the `aws_s3_bucket` resource:
+
+```terraform
+resource "aws_s3_bucket" "log_bucket" {
+  # ... other configuration ...
+  bucket = "example-log-bucket"
+}
+
+resource "aws_s3_bucket" "example" {
+  # ... other configuration ...
+}
+
+resource "aws_s3_bucket_logging" "example" {
+  bucket        = aws_s3_bucket.example.id
+  target_bucket = aws_s3_bucket.log_bucket.id
+  target_prefix = "log/"
+}
+```
+
+It is then recommended running `terraform import` on each new resource to prevent data loss, e.g.
+
+```shell
+$ terraform import aws_s3_bucket_logging.example example
+aws_s3_bucket_logging.example: Importing from ID "example"...
+aws_s3_bucket_logging.example: Import prepared!
+  Prepared aws_s3_bucket_logging for import
+aws_s3_bucket_logging.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.
+```
+
 ### `request_payer` Argument deprecation
 
 Switch your Terraform configuration to the `aws_s3_bucket_request_payment_configuration` resource instead.