Skip to content

Commit

Permalink
docs: adjust change log entries, and update HACKING.md to match (#1159)
Browse files Browse the repository at this point in the history 
Minor adjustments to the way that we record changes:

* Add more structure to [CHANGES](CHANGES.md): group changes by the same
types of groups as in our conventional commit messages (but with full
words rather than abbreviations), and add the GitHub PR number that
introduced the change
* Include all non-internal changes in [CHANGES](CHANGES.md)
* Remove "New in" notes from the API documentation (we want everyone to
regularly update to the latest version, not pick a version that has
whatever they need, and work hard to make this as easy as possible)
* Update [HACKING](HACKING.md) to reflect these process changes

These changes are backported to ops 2.7, which is where the CHANGES file
started.
  • Loading branch information
@tonyandrewmeyer
tonyandrewmeyer authored Mar 26, 2024
1 parent e8305f6 commit d4eb977
Show file tree
Hide file tree
Showing 5 changed files with 168 additions and 54 deletions.
147 changes: 120 additions & 27 deletions CHANGES.md
View file
Original file line number Diff line number Diff line change
@@ -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)
66 changes: 48 additions & 18 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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'`).
3 changes: 0 additions & 3 deletions ops/framework.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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``.
"""
Expand Down
4 changes: 0 additions & 4 deletions ops/model.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 0 additions & 2 deletions ops/testing.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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``.
Expand Down

0 comments on commit d4eb977

Please sign in to comment.