From efc0ae5db93d34a0e9a3c65ead7e184db464baee Mon Sep 17 00:00:00 2001
From: Alexey Shalaev <75322386+AlexeyShalaev@users.noreply.github.com>
Date: Sun, 6 Sep 2026 21:51:09 +0300
Subject: [PATCH] docs: an upgrade note for the unified TTL defaults

The squash merge of #22 dropped the breaking-change footer its commits carried,
so release-please read the release as a patch and the changelog would not have
mentioned the change in defaults. This restores the note and gives the constants
their values in the user guide, with the line to add to keep the old behaviour.

BREAKING CHANGE: DEFAULT_TTL_MINUTES is 60 (was 30) and MAX_TTL_SECONDS is
2592000 (was 86400), so IdempotencyDomainService() built without arguments now
keeps records for an hour and accepts a TTL of up to 30 days. Pass
default_ttl_minutes=30 and max_ttl_seconds=86400 to keep the old values.
---
 docs/user_guide.md | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/docs/user_guide.md b/docs/user_guide.md
index 89141b2..dc970d1 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -247,10 +247,29 @@ repo = RedisAsyncIdempotencyRepository(
 
 ### Constants
 
-These three defaults are the same numbers `BaseIdempotencySettings` uses for its own fields.
-See `idempotency_kit.core.constants` for:
-- `MAX_KEY_LENGTH`, `MAX_OPERATION_LENGTH`
-- `DEFAULT_TTL_MINUTES`, `MIN_TTL_SECONDS`, `MAX_TTL_SECONDS`
+`idempotency_kit.core.constants` is the single source for the TTL defaults, and
+`BaseIdempotencySettings` takes its field defaults from it — build the service by hand or
+from settings and you get the same numbers.
+
+| Constant | Value | What it bounds |
+|---|---|---|
+| `DEFAULT_TTL_MINUTES` | 60 | how long a record is kept when no TTL is given |
+| `MIN_TTL_SECONDS` | 60 | the floor every TTL is raised to |
+| `MAX_TTL_SECONDS` | 2592000 | the ceiling, thirty days |
+
+`MAX_KEY_LENGTH` and `MAX_OPERATION_LENGTH` live beside them.
+
+#### Upgrading
+
+These numbers used to depend on how the service was built: `IdempotencyDomainService`
+defaulted to 30 minutes with a 24-hour ceiling, while `BaseIdempotencySettings` shipped 60
+minutes and 30 days. They agree now, and the wider pair won — narrowing would have started
+rejecting TTLs that work today, and an out-of-range TTL is swallowed, so those operations
+would have gone quietly uncached rather than failing loudly.
+
+So a service built with no arguments now keeps records for an hour rather than half of one.
+Pass `default_ttl_minutes=30` and `max_ttl_seconds=86400` explicitly to keep the old
+behaviour.
 
 ### Key Scope and Format
 The same `idempotency_key` can be used for different operations (e.g., `user.create` and `identifier.attach`) because the repository prefixes the key with the operation name.