Repository navigation
Add the deprecations tooling - #585
Merged
Merged
Conversation
github-actions
Bot
added
part:docs
The deprecations guide builds on `frequenz.core.warnings`, which provides `deprecated_aliases()` to keep old import paths working and `ignoring_deprecations()` to use deprecated symbols internally without warning users twice. The lower bound is 1.6.0 because that release makes the warnings follow the guide: `since` is only used for the documentation and no longer appears in the warning, and it can be combined with a custom `message`. Starting from that version also avoids having to rewrite the tests that match the warnings later. The upper bound excludes the next major version, as usual. `frequenz-core` 1.6.0 requires `typing-extensions >= 4.13.0`, so raise that floor too; otherwise the minimum dependencies can't be installed together (`nox -s pytest_min` fails to resolve them). Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Replace the warning flags in `addopts` with the `filterwarnings` the deprecations guide recommends: every warning is an error, except that deprecations coming from dependencies are only reported once, so they don't fail the test suite. Add the guide's last entry too, which makes using a symbol this project deprecated itself an error. This way the project never releases code that still uses its own deprecated symbols, which users would get as warnings they can do nothing about. It only matches messages starting with `frequenz.channels.<symbol> is deprecated`, so it doesn't affect the existing deprecations (`Broadcast`, `Anycast`, `OptionalReceiver` and the `close()` methods), whose messages don't follow that pattern; the new ones will. The entry goes after the `once::` ones because later filters take precedence. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
The deprecations guide documents every deprecation with a `Deprecated:` admonition, but Material for MkDocs only styles a fixed set of kinds, so it would render without a title style or icon. Add the CSS for the `deprecated` kind, copied from the repository configuration template (frequenz-repo-config-python#641, merged but not released yet), so this file stays identical to the one the next release generates and the migration doesn't change it. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
`BroadcastChannel` is built on top of `Broadcast`, so every call to `BroadcastChannel()` emitted `Broadcast`'s deprecation warning. Users can't do anything about it, as they aren't using `Broadcast` at all, and it hid the warnings that matter. Wrap only the internal `Broadcast` creation in `ignoring_deprecations()` instead of using `warnings.catch_warnings()`, which resets the deduplication history of the whole program, as the deprecations guide recommends. This is enough for v1.x.x; v2.x.x will fix it differently. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Mention the new `frequenz-core` dependency, which is visible to users when they upgrade, and that `BroadcastChannel()` no longer emits the `Broadcast` deprecation warning. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
llucax
force-pushed
the
deprecations-tooling
branch
from
November 5, 2026 12:42
1e2bb5d to
2e34599
Compare
llucax
marked this pull request as ready for review
November 5, 2026 12:44
llucax
requested review from
a team,
daniel-zullo-frequenz and
shsms
and removed request for
a team
November 5, 2026 12:44
llucax
enabled auto-merge
November 5, 2026 12:45
shsms
approved these changes
Nov 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add the tooling the deprecations guide needs, before deprecating anything for v2.0.0 (#365).
frequenz-core >= 1.6.0, < 2as a runtime dependency, and raise thetyping-extensionsfloor to>= 4.13.0, which core 1.6.0 requires.filterwarnings, including the entry that makes this project's own deprecations an error. The existing deprecation messages don't match it, so the tests still pass.deprecatedadmonition style todocs/_css/mkdocstrings.css, copied from Document deprecations with aDeprecated:admonition frequenz-repo-config-python#641 (merged, not released yet).BroadcastChannel()from emittingBroadcast's deprecation warning, with a test.The
griffe-frequenz-coreextension is not enabled: the release that readsfrequenz-core1.6's arguments is not out yet (v1.0.0 is the latest), so theDeprecated:notices will be written by hand for now.Fixes #576