From ac964443ce2f41417c0cb36d8e50ee4465bb3f6f Mon Sep 17 00:00:00 2001
From: "coipond-writer[bot]"
 <309805719+coipond-writer[bot]@users.noreply.github.com>
Date: Tue, 11 Aug 2026 22:43:47 +0200
Subject: [PATCH 1/2] Document force: shutdown parameter and
 graceful-by-default behavior

waterdrop/lib/waterdrop/connection_pool.rb: instance #shutdown(force: false)
(line 247) and class-level ConnectionPool.shutdown(force: false)
(line 118), both aliased to #close, now close pooled producers
gracefully by default (flushing buffered messages) instead of always
force-closing and purging. Per the docstring: "Defaults to false:
producers are closed gracefully so in-flight messages are flushed
instead of being silently dropped when the broker is slow or
unreachable." force: true restores the old force-close-and-purge
behavior.

The page showed only the bare .close call with no mention of force: or
the behavior change. Added documentation of the default and the force:
option.

Fixes #44807.
---
 WaterDrop/Connection-Pool.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/WaterDrop/Connection-Pool.md b/WaterDrop/Connection-Pool.md
index 3ca7a0ab..42133e67 100644
--- a/WaterDrop/Connection-Pool.md
+++ b/WaterDrop/Connection-Pool.md
@@ -60,6 +60,13 @@ To use connection pools with WaterDrop:
     WaterDrop::ConnectionPool.close
     ```
 
+    By default, `#close` (an alias for `#shutdown`) closes each pooled producer **gracefully**: buffered messages are flushed instead of being silently dropped, even if the broker is slow or unreachable. Pass `force: true` to force-close each producer instead, purging any messages that do not flush within the producer's max wait timeout:
+
+    ```ruby
+    # Force-close, purging any messages that don't flush in time
+    WaterDrop::ConnectionPool.close(force: true)
+    ```
+
     !!! note "Auto-Closing in Karafka Applications"
 
         When using the default connection pool within Karafka framework processes, the connection pool is automatically closed during framework shutdown, similar to how the default producer is handled. You do not need to close it manually in Karafka processes.

From 6534c22e1ed61dedc22c0a8e17aa2a992744e503 Mon Sep 17 00:00:00 2001
From: "coipond-writer[bot]"
 <309805719+coipond-writer[bot]@users.noreply.github.com>
Date: Wed, 12 Aug 2026 10:05:19 +0200
Subject: [PATCH 2/2] Remove unnecessary bold around "gracefully" per review
 feedback

---
 WaterDrop/Connection-Pool.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/WaterDrop/Connection-Pool.md b/WaterDrop/Connection-Pool.md
index 42133e67..3a1720ed 100644
--- a/WaterDrop/Connection-Pool.md
+++ b/WaterDrop/Connection-Pool.md
@@ -60,7 +60,7 @@ To use connection pools with WaterDrop:
     WaterDrop::ConnectionPool.close
     ```
 
-    By default, `#close` (an alias for `#shutdown`) closes each pooled producer **gracefully**: buffered messages are flushed instead of being silently dropped, even if the broker is slow or unreachable. Pass `force: true` to force-close each producer instead, purging any messages that do not flush within the producer's max wait timeout:
+    By default, `#close` (an alias for `#shutdown`) closes each pooled producer gracefully: buffered messages are flushed instead of being silently dropped, even if the broker is slow or unreachable. Pass `force: true` to force-close each producer instead, purging any messages that do not flush within the producer's max wait timeout:
 
     ```ruby
     # Force-close, purging any messages that don't flush in time