docs: note about repeatedly setting secret value in Juju 3.6 (#1366)

https://warthogs.atlassian.net/browse/CHARMTECH-171

---------

Co-authored-by: Tony Meyer <[email protected]>

docs/custom_conf.py

@@ -379,7 +379,7 @@ def run(self):
             messages = []
         if self.content:
             node += self.parse_content_to_nodes()
-        classes = ['versionmodified', self.change, 'jujuversion']
+        classes = ['versionmodified', self.change]
         if len(node) > 0 and isinstance(node[0], nodes.paragraph):
             # The contents start with a paragraph.
             if node[0].rawsource:
@@ -418,11 +418,17 @@ class JujuAdded(JujuVersion):
     text = 'Added'
 
 
+class JujuChanged(JujuVersion):
+    change = 'changed'
+    text = 'Changed'
+
+
 class JujuRemoved(JujuVersion):
     change = 'removed'
     text = 'Scheduled for removal'
 
 
 def setup(app):
-    app.add_directive('jujuversion', JujuAdded)
+    app.add_directive('jujuadded', JujuAdded)
+    app.add_directive('jujuchanged', JujuChanged)
     app.add_directive('jujuremoved', JujuRemoved)

docs/requirements.txt

@@ -117,7 +117,7 @@ sphinx==8.0.2
     #   sphinx-tabs
     #   sphinxcontrib-jquery
     #   sphinxext-opengraph
-sphinx-autobuild==2024.4.16
+sphinx-autobuild==2024.9.3
     # via ops (pyproject.toml)
 sphinx-basic-ng==1.0.0b2
     # via furo

ops/charm.py

@@ -837,7 +837,7 @@ def restore(self, snapshot: Dict[str, Any]):
 class PebbleCustomNoticeEvent(PebbleNoticeEvent):
     """Event triggered when a Pebble notice of type "custom" is created or repeats.
 
-    .. jujuversion:: 3.4
+    .. jujuadded:: 3.4
     """
 
 
@@ -884,7 +884,7 @@ class PebbleCheckFailedEvent(PebbleCheckEvent):
     if the check is currently failing, check the current status with
     ``event.info.status == ops.pebble.CheckStatus.DOWN``.
 
-    .. jujuversion:: 3.6
+    .. jujuadded:: 3.6
     """
 
 
@@ -895,7 +895,7 @@ class PebbleCheckRecoveredEvent(PebbleCheckEvent):
     state (not simply failed, but failed at least as many times as the
     configured threshold).
 
-    .. jujuversion:: 3.6
+    .. jujuadded:: 3.6
     """
 
 
@@ -944,7 +944,7 @@ class SecretChangedEvent(SecretEvent):
     :meth:`event.secret.get_content() <ops.Secret.get_content>` with ``refresh=True``
     to tell Juju to start tracking the new revision.
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
         Charm secrets added in Juju 3.0, user secrets added in Juju 3.3
     """
 
@@ -956,7 +956,7 @@ class SecretRotateEvent(SecretEvent):
     be rotated. The event will keep firing until the owner creates a new
     revision by calling :meth:`event.secret.set_content() <ops.Secret.set_content>`.
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
     """
 
     def defer(self) -> NoReturn:
@@ -983,7 +983,7 @@ class SecretRemoveEvent(SecretEvent):
     remove the now-unused revision. If the charm does not, then the event will
     be emitted again, when further revisions are ready for removal.
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
     """
 
     def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int):
@@ -1020,7 +1020,7 @@ class SecretExpiredEvent(SecretEvent):
     must be removed. The event will keep firing until the owner removes the
     revision by calling :meth:`event.secret.remove_revision() <ops.Secret.remove_revision>`.
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
     """
 
     def __init__(self, handle: 'Handle', id: str, label: Optional[str], revision: int):
@@ -1213,29 +1213,29 @@ class CharmEvents(ObjectEvents):
     """Triggered by Juju on the observer when the secret owner changes its contents (see
     :class:`SecretChangedEvent`).
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
         Charm secrets added in Juju 3.0, user secrets added in Juju 3.3
     """
 
     secret_expired = EventSource(SecretExpiredEvent)
     """Triggered by Juju on the owner when a secret's expiration time elapses (see
     :class:`SecretExpiredEvent`).
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
     """
 
     secret_rotate = EventSource(SecretRotateEvent)
     """Triggered by Juju on the owner when the secret's rotation policy elapses (see
     :class:`SecretRotateEvent`).
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
     """
 
     secret_remove = EventSource(SecretRemoveEvent)
     """Triggered by Juju on the owner when a secret revision can be removed (see
     :class:`SecretRemoveEvent`).
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
     """
 
     collect_app_status = EventSource(CollectStatusEvent)

ops/model.py

@@ -280,7 +280,7 @@ def get_secret(self, *, id: Optional[str] = None, label: Optional[str] = None) -
         again, unless ``refresh=True`` is used, or :meth:`Secret.set_content`
         has been called.
 
-        .. jujuversion:: 3.0
+        .. jujuadded:: 3.0
             Charm secrets added in Juju 3.0, user secrets added in Juju 3.3
 
         Args:
@@ -465,7 +465,7 @@ def add_secret(
     ) -> 'Secret':
         """Create a :class:`Secret` owned by this application.
 
-        .. jujuversion:: 3.0
+        .. jujuadded:: 3.0
 
         Args:
             content: A key-value mapping containing the payload of the secret,
@@ -1246,7 +1246,7 @@ class Secret:
     All secret events have a :code:`.secret` attribute which provides the
     :class:`Secret` associated with that event.
 
-    .. jujuversion:: 3.0
+    .. jujuadded:: 3.0
         Charm secrets added in Juju 3.0, user secrets added in Juju 3.3
     """
 
@@ -1460,6 +1460,10 @@ def set_content(self, content: Dict[str, str]):
         secret no longer exists, this method will succeed, but the unit will go
         into error state on completion of the current Juju hook.
 
+        .. jujuchanged:: 3.6
+            A new secret revision will *not* be created if the content being set
+            is identical to the latest revision.
+
         Args:
             content: A key-value mapping containing the payload of the secret,
                 for example :code:`{"password": "foo123"}`.
@@ -2939,7 +2943,7 @@ def send_signal(self, sig: Union[int, str], *service_names: str):
     def get_notice(self, id: str) -> pebble.Notice:
         """Get details about a single notice by ID.
 
-        .. jujuversion:: 3.4
+        .. jujuadded:: 3.4
 
         Raises:
             ModelError: if a notice with the given ID is not found
@@ -2964,7 +2968,7 @@ def get_notices(
         See :meth:`ops.pebble.Client.get_notices` for documentation of the
         parameters.
 
-        .. jujuversion:: 3.4
+        .. jujuadded:: 3.4
         """
         return self._pebble.get_notices(
             users=users,

tox.ini

@@ -54,10 +54,8 @@ description = Live development: build the Sphinx docs with autoreloading enabled
 deps = {[testenv:docs]deps}
 commands_pre =
     {[testenv:docs]commands_pre}
-# https://github.com/sphinx-doc/sphinx-autobuild/issues/170
-change_dir = {tox_root}/docs
 commands =
-    sphinx-autobuild ./ ./_build/html --watch . --port 8000
+    sphinx-autobuild docs/ docs/_build/html --watch ops/ --port 8000 {posargs}
 
 [testenv:fmt]
 description = Apply coding style standards to code