docs: adjust change log entries, and update HACKING.md to match

CHANGES.md

@@ -1,38 +1,131 @@
-# 2.12.0
+# Next - TBD
 
-* Updated Pebble Notices `get_notices` parameter name to `users=all` (previously `select=all`).
-* Added `Model.get_cloud_spec` which uses the `credential-get` hook tool to get details of the cloud where the model is deployed.
-* Refactored main.py, creating a new `_Manager` class.
+## Features
 
-# 2.11.0
+* Add `Model.get_cloud_spec` which uses the `credential-get` hook tool to get details of the cloud where the model is deployed (#1152)
 
-* `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.
-* 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()`.
+## Fixes
 
-# 2.10.0
+* Update Pebble Notices `get_notices` parameter name to `users=all` (previously `select=all`) (#1146)
+* Warn when an observer weakref is lost (#1142)
+* More robust validation of observer signatures (#1147)
+* Change `Model.relation.app` type from `Application|None` to `Application` (#1151)
+* Fix attaching storage in Harness before `begin` (#1150)
 
-* Added support for Pebble Notices (`PebbleCustomNoticeEvent`, `get_notices`, and so on)
-* Added `Relation.active`, and excluded inactive relations from `Model.relations`
-* Added full support for charm metadata v2 (in particular, extended `ContainerMeta`,
-  and various info links in `CharmMeta`)
+## Refactoring
 
-# 2.9.0
+* Refactor main.py, creating a new `_Manager` class (#1085)
 
-* Added log target support to `ops.pebble` layers and plans
-* Added `Harness.run_action()`, `testing.ActionOutput`, and `testing.ActionFailed`
+## Documentation
 
-# 2.8.0
+* Use "integrate with" rather than "relate to" (#1145)
+
+# 2.11.0 - 29 Feb 2024
+
+## 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)
+* Add `ActionEvent.id`, exposing the JUJU_ACTION_UUID environment variable (#1124)
+* Add 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()` (#1134)
+
+## Fixes
+
+* The remote app name (and its databag) is now consistently available in relation-broken events (#1130)
+
+## Documentation
+
+* Improve the `can_connect()` API documentation (#1123)
+
+## Tooling
+
+* Use ruff for linting (#1120, #1139, #1114)
+
+# 2.10.0 - 31 Jan 2024
+
+## Features
+
+* Add support for Pebble Notices (`PebbleCustomNoticeEvent`, `get_notices`, and so on) (#1086, #1100)
+* Add `Relation.active`, and excluded inactive relations from `Model.relations` (#1091)
+* Add full support for charm metadata v2 (in particular, extended `ContainerMeta`,
+  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
+
+* Add 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 - 30 Nov 2023
+
+## Features
+
+* Add log target support to `ops.pebble` layers and plans (#1074)
+* Add `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
+
+* Refresh README (#1052)
+* Clarify how custom events are emitted (#1072)
+* Fix the `Harness.get_filesystem_root` example (#1065)
+
+# 2.8.0 - 25 Oct 2023
+
+## Features
+
+* Add `Unit.reboot()` and `Harness.reboot_count` (#1041)
+* Add `RelationMeta.optional` (#1038)
+* Raise a clearer exception when the Pebble socket is missing (#1049)
+
+## Fixes
 
-* Added `Unit.reboot()` and `Harness.reboot_count``
-* Added `RelationMeta.optional`
 * 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
+* Narrow 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)
 
-# 2.7.0
+## Documentation
 
-* Added Unit.set_ports()
+* Notes that status changes are immediate (#1029)
+* Clarifies `set_results` maximum size (#1047)
+* Expands documentation on when exceptions may be raised (#1044)
+* Makes `pebble.Client.remove_path` and `Container.remove_path` docs consistent (#1031)
+
+## Tooling
+
+* Adds type hinting across the test suite (#1017, #1015, #1022, #1023, #1025, #1028, #1030, #1018, #1034, #1032)
+
+# 2.7.0 - 29 Sept 2023
+
+## Features
+
+* Adds Unit.set_ports() (#1005)
 * Type checks now allow comparing a `JujuVersion` to a `str`
-* Renamed `OpenPort` to `Port` (`OpenPort` remains as an alias)
+* Rename `OpenPort` to `Port` (`OpenPort` remains as an alias)
+
+## Documentation
+
+* Reduces the amount of detail in open/close port methods (#1006)
+* Removes you/your from docstrings (#1003)
+* Minor improvements to HACKING (#1016)
+
+## Tooling
+
+* Extends 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.
+
+During the release process, changes 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:
 
@@ -223,23 +234,42 @@ the build frontend is [build](https://pypi.org/project/build/).
 
 To make a release of the ops library, do the following:
 
-1. Open a PR to change [version.py][ops/version.py]'s `version` to the
-   [appropriate string](https://semver.org/), and get that merged to main.
-2. Visit the [releases page on GitHub](https://github.com/canonical/operator/releases).
-3. Click "Draft a new release"
-4. The "Release Title" is simply the full version number, in the form <major>.<minor>.<patch>
+1. Visit the [releases page on GitHub](https://github.com/canonical/operator/releases).
+2. Click "Draft a new release"
+3. The "Release Title" is simply the full version number, in the form <major>.<minor>.<patch>
    and a brief summary of the main changes in the release
    E.g. 2.3.12 Bug fixes for the Juju foobar feature when using Python 3.12
-5. Drop notes and a changelog in the description.
-6. When you are ready, click "Publish". (If you are not ready, click "Save as Draft".) Wait for the new version to be published successfully to [the PyPI project](https://pypi.org/project/ops/).
-7. Open a PR to change [version.py][ops/version.py]'s `version` to the expected
-   next version, with "+dev" appended (for example, if 3.14.1 is the next expected version, use
-   `'3.14.1.dev0'`).
-
-This will trigger an automatic build for the Python package and publish it to PyPI (authorization is handled via a [Trusted Publisher](https://docs.pypi.org/trusted-publishers/) relationship).
+4. Use the "Generate Release Notes" button to get a copy of the changes into the
+   notes field.
+5. Group the changes by the commit type (feat, fix, etc), stripping that prefix
+   from the bullet point, and using the full name ("Features", not "feat") for
+   the group heading.
+6. Where appropriate, collapse multiple tightly related bullet points into a
+   single point that refers to multiple commits.
+7. Create a new branch, and copy this text to the [CHANGES.md](CHANGES.md) file,
+   stripping out links, who did each commit, the new contributor list, and the
+   link to the full changelog.
+8. Change [version.py][ops/version.py]'s `version` to the
+   [appropriate string](https://semver.org/).
+9. Add, commit, and push, and open a PR to get the changelog and version bump
+   into main (and get it merged).
+10. Back in the GitHub releases page, tweak the release notes - for example,
+   you might want to have a short paragraph at the intro on particularly
+   noteworthy changes.
+11. Have someone else in the Charm-Tech team proofread the release notes.
+12. When you are ready, click "Publish". (If you are not ready, click "Save as Draft".)
+
+This will trigger an automatic build for the Python package and publish it to
+[PyPI](https://pypi.org/project/ops/)) (authorisation is handled via a
+[Trusted Publisher](https://docs.pypi.org/trusted-publishers/) relationship).
+Note that it sometimes take a bit of time for the new release to show up.
 
 See [.github/workflows/publish.yml](.github/workflows/publish.yml) for details. (Note that the versions in publish.yml refer to versions of the GitHub actions, not the versions of the ops library.)
 
 You can troubleshoot errors on the [Actions Tab](https://github.com/canonical/operator/actions).
 
-Announce the release on [Discourse](https://discourse.charmhub.io/c/framework/42) and [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+13. Announce the release on [Discourse](https://discourse.charmhub.io/c/framework/42) and [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+
+14. Open a PR to change [version.py][ops/version.py]'s `version` to the expected
+   next version, with "+dev" appended (for example, if 3.14.1 is the next expected version, use
+   `'3.14.1.dev0'`).

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

@@ -707,8 +707,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.
@@ -743,8 +741,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

@@ -1868,8 +1868,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``.