Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readme.md cleanup #127

Open
PietroPasotti opened this issue Dec 5, 2023 · 4 comments
Open

Readme.md cleanup #127

PietroPasotti opened this issue Dec 5, 2023 · 4 comments
Assignees

Comments

@PietroPasotti
Copy link
Contributor

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
@PietroPasotti
Copy link
Contributor Author

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.

@PietroPasotti
Copy link
Contributor Author

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

@benhoyt
Copy link
Collaborator

benhoyt commented Nov 12, 2024

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants