canonical
Improve the README, including updating the example charm
The README (which also displays on PyPI) could be more approachable for people who want to quickly get the point of Ops and try out Ops.
Mainly, I think it would be great if the README had a tight, self-contained set of steps for making a simple charm and showing what the charm does when deployed & tested. We should be able to take advantage of Concierge and an improved Charmcraft profile (upcoming) to limit the number of steps.
Definitely worth discussing how to improve the README. However, I'm a little skeptical that "self-contained steps for making a simple charm" should be in the README. Shouldn't that be in a tutorial doc? And if our existing tutorials are too "un-tight", should we focus our effort there, or add another basic tutorial?
Let's discuss further, to clarify the best way to make use of the README. I do agree with this sentiment:
And if our existing tutorials are too "un-tight", should we focus our effort there, or add another basic tutorial?
With the caveat that a tutorial is intended to be for learning. What I'd like to see somewhere is an answer to the question "I just want to have a basic charm deployed from source on my machine, so that I can inspect it myself" - I guess what I have in mind is more like a script than a tutorial or steps that need to be followed manually.
I'm tagging this one as roadmap, as the README currently relies on getting an httpbin charm from charmcraft init. We're planning to remove this profile in Charmcraft 4.0 (see https://github.com/canonical/charmcraft/pull/2295). So we'll either need to reference the same charm from within the Ops repo (see #1743) or switch to a different example.
Related: https://github.com/canonical/operator/issues/1803
Per Dima's point on https://github.com/canonical/operator/issues/1817, while doing this work we should decide whether the README should include unit testing.
@dwilding Do you still think this needs doing? Should we consider it for the 26.04 roadmap?
My current thinking is, let's make the README less like a tutorial (in contrast to my original idea). Better for people to work through our actual tutorials. I think the README can be cut down to a survey of the httpbin demo charm: here's where Ops is used, here's where unit testing happens, etc. We've made a good number of improvements to that charm since migrating it from Charmcraft.
And to answer your other question, I think that'll be most practical for 26.04, yes.
Also worth considering separating the README pushed to PyPI from the README.md (perhaps open a separate issue for PyPI if needed?)