diff --git a/CHANGES.md b/CHANGES.md index cea76b8b0..49b17a746 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,40 +1,133 @@ -# 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. -* Fixed an issue where `pebble.Client.exec` might leak a `socket.timeout` (`builtins.TimeoutError`) exception. -* Updated code examples in the docstring of `ops.testing` from unittest to pytest style. -* Refactored main.py, creating a new `_Manager` class. +## Features -# 2.11.0 +* Added `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) +* Fixed an issue where `pebble.Client.exec` might leak a `socket.timeout` (`builtins.TimeoutError`) exception (#1155) -* 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) +* Updated code examples in the docstring of `ops.testing` from unittest to pytest style (#1157) + +# 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) diff --git a/HACKING.md b/HACKING.md index 9523d526c..2ee4e5610 100644 --- a/HACKING.md +++ b/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 .. +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 .. 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'`). diff --git a/ops/framework.py b/ops/framework.py index 07294ed7a..23b982c7b 100644 --- a/ops/framework.py +++ b/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``. """ diff --git a/ops/model.py b/ops/model.py index d028febbf..7ca4e1381 100644 --- a/ops/model.py +++ b/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. diff --git a/ops/testing.py b/ops/testing.py index 7e60d4d16..47c79eb84 100644 --- a/ops/testing.py +++ b/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``.