Adjust change log entries, and update HACKING.md to match.

CHANGES.md

@@ -1,32 +1,109 @@
 # 2.11.0
 
-* `StopEvent`, `RemoveEvent`, and all `LifeCycleEvent`s are no longer deferrable, and will raise a `RuntimeError` if `defer()` is called on the event object.
-* The remote app name (and its databag) is now consistently available in relation-broken events.
-* Added `ActionEvent.id`, exposing the JUJU_ACTION_UUID environment variable.
+Features:
+
+* `StopEvent`, `RemoveEvent`, and all `LifeCycleEvent`s are no longer deferrable, and will raise a `RuntimeError` if `defer()` is called on the event object (#1122)
+* Added `ActionEvent.id`, exposing the JUJU_ACTION_UUID environment variable (#1124)
 * Added support for creating `pebble.Plan` objects by passing in a `pebble.PlanDict`, the
-  ability to compare two `Plan` objects with `==`, and the ability to create an empty Plan with `Plan()`.
+  ability to compare two `Plan` objects with `==`, and the ability to create an empty Plan with `Plan()` (#1134)
+
+Fixes:
+
+* The remote app name (and its databag) is now consistently available in relation-broken events (#1130)
+
+Documentation:
+
+* Improved the `can_connect()` API documentation (#1123)
+
+Tooling:
+
+* Use ruff for linting (#1120, #1139, #1114)
 
 # 2.10.0
 
-* Added support for Pebble Notices (`PebbleCustomNoticeEvent`, `get_notices`, and so on)
-* Added `Relation.active`, and excluded inactive relations from `Model.relations`
+Features:
+
+* Added support for Pebble Notices (`PebbleCustomNoticeEvent`, `get_notices`, and so on) (#1086, #1100)
+* Added `Relation.active`, and excluded inactive relations from `Model.relations` (#1091)
 * Added full support for charm metadata v2 (in particular, extended `ContainerMeta`,
-  and various info links in `CharmMeta`)
+  and various info links in `CharmMeta`) (#1106)
+* When handling actions, print uncaught exceptions to stderr (#1087)
+* Raise `ModelError` in Harness if an invalid status is set (#1107)
+
+Fixes:
+
+* Added Pebble log targets and checks to testing plans (#1111)
+* CollectStatusEvent is now a LifecycleEvent (#1080)
+
+Documentation:
+
+* Update README to reflect charmcraft init changes (#1089)
+* Add information on pushing locked/bind-mount files (#1094)
+* Add instructions for using a custom version of ops to HACKING (#1092)
+
+Tooling:
+
+* Use pyproject.toml for building (#1068)
+* Update to the latest version of Pyright (#1105)
 
 # 2.9.0
 
-* Added log target support to `ops.pebble` layers and plans
-* Added `Harness.run_action()`, `testing.ActionOutput`, and `testing.ActionFailed`
+Features:
+
+* Added log target support to `ops.pebble` layers and plans (#1074)
+* Added `Harness.run_action()`, `testing.ActionOutput`, and `testing.ActionFailed` (#1053)
+
+Fixes:
+
+* Secret owners no longer auto-peek, and can use refresh, in Harness, and corrected secret access for non-leaders (#1067, #1076)
+* Test suite adjustments to pass with Python 3.12 (#1081)
+
+Documentation:
+
+* Refreshed README (#1052)
+* Clarify how custom events are emitted (#1072)
+* Fixed the `Harness.get_filesystem_root` example (#1065)
 
 # 2.8.0
 
-* Added `Unit.reboot()` and `Harness.reboot_count``
-* Added `RelationMeta.optional`
+Features:
+
+* Added `Unit.reboot()` and `Harness.reboot_count` (#1041)
+* Added `RelationMeta.optional` (#1038)
+* Clearer exception when the Pebble socket is missing (#1049)
+
+Fixes:
+
 * The type of a `Handle`'s `key` was expanded from `str` to `str|None`
 * Narrowed types of `app` and `unit` in relation events to exclude `None` where applicable
+* `push_path` and `pull_path` now include empty directories (#1024)
+* Harness's `evaluate_status` resets collected statuses (#1048)
+
+Documentation:
+
+* Noted that status changes are immediate (#1029)
+* Clarified `set_results` maximum size (#1047)
+* Expanded documentation on when exceptions may be raised (#1044)
+* Made `pebble.Client.remove_path` and `Container.remove_path` docs consistent (#1031)
+
+Tooling:
+
+* Added type hinting across the test suite (#1017, #1015, #1022, #1023, #1025, #1028, #1030, #1018, #1034, #1032)
 
 # 2.7.0
 
-* Added Unit.set_ports()
+Features:
+
+* Added Unit.set_ports() (#1005)
 * Type checks now allow comparing a `JujuVersion` to a `str`
 * Renamed `OpenPort` to `Port` (`OpenPort` remains as an alias)
+
+Documentation:
+
+* Reduce the amount of detail in open/close port methods (#1006)
+* Remove you/your from docstrings (#1003)
+* Minor improvements to HACKING (#1016)
+
+Tooling:
+
+* Extend the use of type hints in the test suite (#1008, #1009, #1011, #1012, #1013, #1014, #1004)

HACKING.md

@@ -166,10 +166,6 @@ Each page on [juju.is](https://juju.is/docs/sdk) has a link at the bottom that
 takes you to the corresponding Discourse page where docs can be commented on
 and edited (if you have earned those privileges).
 
-The ops library's API reference is automatically built and published to
-[ops.readthedocs.io](https://ops.readthedocs.io/en/latest/).  Please be complete with
-docstrings and keep them informative for _users_.
-
 Currently we don't publish separate versions of documentation for separate releases.  Instead, new features should be sign-posted (for example, as done for [File and directory existence in 1.4](https://juju.is/docs/sdk/interact-with-pebble#heading--file-exists)) with Markdown like this:
 
 ```markdown
@@ -178,7 +174,22 @@ Currently we don't publish separate versions of documentation for separate relea
 
 next to the relevant content (e.g. headings, etc.).
 
-Noteworthy changes should also get a new entry in [CHANGES.md](CHANGES.md).
+The ops library's API reference is automatically built and published to
+[ops.readthedocs.io](https://ops.readthedocs.io/en/latest/).  Please be complete with
+docstrings and keep them informative for _users_. The published docs are always
+for the in-development (main branch) of ops, and do not include any notes
+indicating changes or additions across versions - we encourage all charmers to
+promptly upgrade to the latest version of ops, and to refer to the release notes
+and changelog for learning about changes.
+
+Changes should also get a new entry in [CHANGES.md](CHANGES.md). These are
+grouped into the same groupings as
+[commit messages](https://www.conventionalcommits.org/en/)
+(feature, fix, documentation, performance, etc). The only exceptions are changes
+that are not visible to the built releases, such as CI workflow changes, or are
+implicit, such as bumping the ops version number. Each entry should be a short,
+single line, bullet point, and should reference the GitHub PR that introduced
+the change (as plain text, not a link).
 
 As noted above, you can generate a local copy of the API reference docs with tox:
 

ops/framework.py

@@ -666,9 +666,6 @@ def set_breakpointhook(self) -> Optional[Any]:
 
         The ``breakpoint()`` function is a Python >= 3.7 feature.
 
-        This method was added in ops 1.0; before that, it was done as
-        part of the Framework's ``__init__``.
-
         Returns:
             The old value of ``sys.breakpointhook``.
         """

ops/model.py

@@ -693,8 +693,6 @@ def set_ports(self, *ports: Union[int, 'Port']) -> None:
         Use :meth:`open_port` and :meth:`close_port` to manage ports
         individually.
 
-        *New in version 2.7*
-
         Args:
             ports: The ports to open. Provide an int to open a TCP port, or
                 a :class:`Port` to open a port for another protocol.
@@ -729,8 +727,6 @@ def reboot(self, now: bool = False) -> None:
         This is not supported on Kubernetes charms, can only be called for the current unit,
         and cannot be used in an action hook.
 
-        *New in version 2.8*
-
         Args:
             now: terminate immediately without waiting for the current hook to complete,
                 restarting the hook after reboot.

ops/testing.py

@@ -1847,8 +1847,6 @@ def run_action(self, action_name: str,
                 ...
             harness.run_action("action-name", params)
 
-        *New in version 2.9*
-
         Args:
             action_name: the name of the action to run, as found in ``actions.yaml``.
             params: override the default parameter values found in ``actions.yaml``.