docs: point the interface docs at charmlibs by tonyandrewmeyer · Pull Request #2710 · canonical/operator

tonyandrewmeyer · 2026-08-30T22:05:08Z

canonical/charm-relation-interfaces was archived in November 2025 and the interfaces now live in the interfaces/ directory of the charmlibs monorepo, so the explanation page, the interface and library how-tos, and the testing docs all point at a repository that isn't the source of truth any more. This updates the repository, the paths (each interface is now interfaces/<name>/interface/v<N>/, with tests/ rather than interface_tests/), and the URLs.

The tooling changed as well, so the how-to now uses just init --interface rather than copying the __template__ directory, and the local test-run section uses .scripts/get-interface-test-targets.py and .scripts/run-interface-tests.py, since run_matrix.py doesn't exist in charmlibs.

I've left the charm-relation-interfaces.md filename and its MyST anchor alone, because three other pages reference it - renaming both is an easy follow-up if you'd prefer that.

Preview.

Fixes #2525, #2549

canonical/charm-relation-interfaces was archived in November 2025 and the interfaces now live in the charmlibs monorepo, under interfaces/, with a per-interface layout of interface/v<N>/{README.md,interface.yaml,schema.py,tests/}. Update the explanation page, the interface and relation how-tos, and the testing docs to match: new repository, new paths, new URLs, and the current tooling (just init --interface for scaffolding, and the .scripts/get-interface-test-targets.py + .scripts/run-interface-tests.py pair in place of the old run_matrix.py).

Add `monorepo` to the custom wordlist, and rename the scaffolding section so it doesn't use `initialiser`, which the US spellcheck rejects.

Co-authored-by: Tony Meyer <tony.meyer@gmail.com>

dwilding · 2026-08-31T23:40:38Z

 ```

-To verify that things work as they should, you can `pip install pytest-interface-tester` and then run `interface_tester discover --include my_fancy_database` from the `charm-relation-interfaces` root.
+To verify that things work as they should, you can `pip install pytest-interface-tester` and then run `interface_tester discover --include my_fancy_database` from the `charmlibs` root.


My agent says interface_tester won't work, because the charmlibs repo uses a different directory structure. See dwilding/basic-charms#67 (which is a bit of a convoluted test, sorry - the workflow agent is only allowed to install things in a charm venv, and interface_tester requires an incompatible Ops version, so the agent had to recreate some of the interface_tester code).

We're going to drop pytest interface tester from charmlibs soon, so we shouldn't recommend it at all here.

james-garner-canonical

Thanks, this is a great start, and it will be really nice to get rid of the misleading recommendations around charm-relation-interfaces. There are some changes we need to make to align with the direction on Charmlibs:

Interface tests are going away, so we should remove all documentation of them from the Ops docs.
Interface structure is going to be flatted (no versioned sub-directories), so we should drop all mention of that here too.

In general I wonder if this has a bit too much detail about things that should probably be documented (better, at all) on the Charmlibs side. I'm happier with that than having nothing at all, but I think ideally we'd get to:

just init --interface actually does scaffold interface docs for you.
Charmlibs docs tell you how to document an interface +/- having a package for it (I have a WIP PR for this canonical/charmlibs#546, but it's blocked on actually making the planned infra changes).
We can cleanly recommend an entry point on Charmhub or the Charmlibs docs for browsing interfaces, rather than saying to search in the repo.

LMK if you'd prefer to land this with more information, and have me remove it as I had info on the Charmlibs side; or land with less information here, and have a small gap until the Charmlibs side lands.

james-garner-canonical · 2026-09-01T05:37:54Z

-Conversely, if the charm you are developing needs some service (a database, an ingress URL, an authentication endpoint...)  you should search `charm-relation-interfaces` to see if there is an interface you can use, and to find existing charms that provide it.
+## Using interface definitions
+
+If you have a charm that provides a service, you should search the [`interfaces` directory in `charmlibs`](https://github.com/canonical/charmlibs/tree/main/interfaces) (or directly Charmhub in the future) and see if an interface exists already, or perhaps a similar one exists that lacks the semantics you need and can be extended to support it.


Probably we should actually direct people to Charmhub's view of interfaces? Or the Charmlibs interface docs, rather than directly at the source?

james-garner-canonical · 2026-09-01T05:38:14Z


-* **the owner of the specification** of the interface, which also owns the tests that can be used to verify "does charm X 'really' support this interface?". This is the `charm-relation-interfaces` repo.
-* **the owner of the implementation** of an interface. In practice, this often is the charm that owns the charm library with the reference implementation for an interface.
+* **the owner of the specification** of the interface, which also owns the tests that can be used to verify "does charm X 'really' support this interface?". This is the relevant interface directory in the [`charmlibs` monorepo](https://github.com/canonical/charmlibs).


We're dropping the tests, so they shouldn't be mentioned here.

james-garner-canonical · 2026-09-01T05:38:50Z

- a list of **reference charms**: these are the charms that implement this interface, typically, the owner of the charm library providing the original implementation.
- the **schema**: pydantic models unambiguously defining the accepted unit and application databag contents for provider and requirer.
- the **interface tests**: python tests that can be run to verify that a charm complies with the interface specification.
+For each interface, the [`interfaces` directory in `charmlibs`](https://github.com/canonical/charmlibs/tree/main/interfaces) hosts a per-interface folder (for example, `interfaces/ingress/`), with the per-version specification under `interface/v<N>/`:


We're going to flatten the versions, so tidier not to document those repository internals here.

james-garner-canonical · 2026-09-01T05:39:11Z

+- the **specification**: a semi-formal definition of the interface's semantics and what its implementations are expected to do, in terms of both the provider and the requirer (`interface/v<N>/README.md`).
+- a list of **reference charms**: the charms that implement this interface, typically the owner of the charm library providing the original implementation (`interface/v<N>/interface.yaml`).
+- the **schema**: pydantic models unambiguously defining the accepted unit and application databag contents for provider and requirer (`interface/v<N>/schema.py`).
+- the **interface tests**: Python tests that can be run to verify that a charm complies with the interface specification (`interface/v<N>/tests/`).


Again, drop these.

james-garner-canonical · 2026-09-01T05:40:18Z

+- the **specification**: a semi-formal definition of the interface's semantics and what its implementations are expected to do, in terms of both the provider and the requirer (`interface/v<N>/README.md`).
+- a list of **reference charms**: the charms that implement this interface, typically the owner of the charm library providing the original implementation (`interface/v<N>/interface.yaml`).
+- the **schema**: pydantic models unambiguously defining the accepted unit and application databag contents for provider and requirer (`interface/v<N>/schema.py`).


These are likely to stay (though we should drop the path specifics here), but I wonder if, rather than this level of detail, we should just point to Charmlibs more vaguely here.

james-garner-canonical · 2026-09-01T05:42:35Z

+├── interface
+│   └── v0
+│       ├── README.md
+│       ├── interface.yaml
+│       ├── schema.py
+│       └── tests
+└── ruff.toml


Actually, just init --interface will scaffold an interface package with no interface docs, so none of this stuff will be there today.

james-garner-canonical · 2026-09-01T05:43:17Z

+These are the steps you need to take in order to register it in the [`charmlibs` monorepo](#charm-relation-interfaces).

-### 1. Clone (a fork of) [the `charm-relation-interfaces` repo](https://github.com/canonical/charm-relation-interfaces) and set up an interface specification folder
+### 1. Clone (a fork of) [the `charmlibs` repo](https://github.com/canonical/charmlibs) and create an interface package


To register an interface you don't need to create a package in charmlibs, you can have an interface docs only directory. We mention this kind of briefly at the end, but I worry that this whole thing steers people in the wrong direction.

The interface how-to pointed at `.scripts/get-interface-test-targets.py` and `.scripts/run-interface-tests.py` in `charmlibs`, but neither script exists - `charmlibs` has no interface test runner, and its CI only validates schemas. It also told readers to run `interface_tester discover` from the `charmlibs` root, which can't work: the collector globs `interfaces/<name>/v*`, whereas `charmlibs` uses `interfaces/<name>/interface/v*`. Replace both with instructions that do work: validate the schema the way `charmlibs` CI does, and verify the tests and the fixture from the charm repository, where `InterfaceTester` supports the new layout via `interface_subdir` and `tests_dir`. Configure those (plus `repo` and `base_path`) in the sample `conftest.py`, since `pytest-interface-tester` still defaults to the archived `charm-relation-interfaces` repo. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSgvey9Q9iQ2zV4mwHdXap

Addresses james-garner-canonical's review. Interface tests are going away in `charmlibs` and the versioned interface sub-directories are being flattened, so documenting either here would be wrong shortly. - Remove the "Write tests for an interface" how-to section and the "Interface testing" section of the testing explanation, along with the remaining recommendations of `pytest-interface-tester`. The one reference left is `interface_tester.schema_base.DataBagSchema`, which interface schemas still subclass today; note that it is expected to change. - Drop `interface/v<N>/` paths throughout, and describe what an interface definition contains rather than the repository layout. - Lead "Register an interface" with creating a docs-only directory, since registering an interface doesn't require publishing a package, and mention `just init --interface` as the route for when you do want a charm library too. - Point at the charmlibs documentation and Charmhub for browsing interfaces, rather than at the repository tree. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSgvey9Q9iQ2zV4mwHdXap

tonyandrewmeyer added 2 commits August 31, 2026 10:03

docs: keep the spelling check happy

b9861cb

Add `monorepo` to the custom wordlist, and rename the scaffolding section so it doesn't use `initialiser`, which the US spellcheck rejects.

tonyandrewmeyer commented Aug 30, 2026

View reviewed changes