charm-relation-interfaces

charm-relation-interfaces copied to clipboard

Right now, the readme.md of all interfaces has a few issues:

• unclear what the purpose of the introductory section is, given that it's always some paraphrase of

"this interface specification is meant to define what a charm providing or requiring a relation with this relation interface."

• too much variability in the way the 'expectations' are stated. If the schema (pydantic or json) is not clear enough, then the tests should make it bulletproof-obvious what a charm is or is not expected to do.
• there is still some lingering confusion in some specifications of whether the norms are behavioral or purely structural (i.e. if the ingress provider is actually expected to do something beyond replying with a syntactically correct url).
• the 'directionality' graphs are somewhat useful, but also that's information that can be derived from the schema. Perhaps we can make the schemas more central and visualize them better?

I think this repo/project would benefit from some cleanup across the readme's to:

• reduce duplication
• uniform things across the interfaces
• make the language more clear in general

I think we should clarify the purpose of the readme and the target audience. If/when it will eventually land in charmhub as interface documentation, we need to make sure it's useful and neat.

couldn't find a way to schedule a meet between us without breaking the world, so let's try to hammer this out asynchronously

@PietroPasotti Could you link to a couple of examples where there's a lot of duplication. I had a quick look around and didn't really see what you are referring to.

Whew this was some time ago. off the top of my head:

• https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/tempo_cluster/v0/README.md
• https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/ingress/v1/README.md
• https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/ingress/v2/README.md
• https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/ingress_per_unit/v0/README.md