From 4f70c5f0b8d760455363d87d516b49a81e5506d9 Mon Sep 17 00:00:00 2001
From: Tony Meyer <tony.meyer@canonical.com>
Date: Thu, 20 Jun 2024 15:07:49 +1200
Subject: [PATCH] Explain the retry behaviour of secret-remote events.

---
 ops/charm.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/ops/charm.py b/ops/charm.py
index 3465c2fad..9a1d79a12 100644
--- a/ops/charm.py
+++ b/ops/charm.py
@@ -905,9 +905,10 @@ class SecretRemoveEvent(SecretEvent):
     observers have updated to that new revision, this event will be fired to
     inform the secret owner that the old revision can be removed.
 
-    Typically, the charm will call
+    After any required cleanup, the charm should call
     :meth:`event.secret.remove_revision() <ops.Secret.remove_revision>` to
-    remove the now-unused revision.
+    remove the now-unused revision. If the charm does not, then the event will
+    be emitted again, when further revisions are ready for removal.
     """
 
     def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int):