docs: small tweaks to best practice blocks
Metadata
Current evaluation
Merged in charmcraft#2452 via commit 655519ae, reclassifying two “manage charms” examples as a tip and making charmcraft.yaml best practices clearer standalone.
Resolution: closed resolved
Reason: PR #2452 merged its documentation updates in commit 655519ae. The changes improve how best-practice blocks appear in Ops documentation and the Charmhub review checklist.
Evaluated by: mr-cal-bot
No scores available.
Issue body
Two small changes to the best practice blocks, to improve how they appear in the consolidated list that will soon be in the Ops docs (https://github.com/canonical/operator/pull/1989), and in the Charmhub public listing review checklist.
* The "manage charms" how-to has two blocks that have examples of good documentation for small/big charms. These aren't really best practices. I've changed them to a tip.
* A few of the best practices in the `charmcraft.yaml` reference don't work very well when removed from the wider context. I've made small adjustments so that they still work in context, but also work if you have the best practice standing on its own.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged in charmcraft#2452 via commit 655519ae, reclassifying two “manage charms” examples as a tip and making charmcraft.yaml best practices clearer standalone. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in charmcraft#2452: reclassified two “manage charms” examples as a tip and revised charmcraft.yaml best-practice blocks for clearer standalone use. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged documentation updates reformatting best practice blocks for standalone display and Charmhub listing. Converted contextual examples to tips and adjusted standalone practices for clarity. Approved by two reviewers and passed CI checks. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates adjusting best practice blocks for standalone display in consolidated docs and Charmhub checklists. Two manage charms examples became tips, and charmcraft.yaml blocks were modified for standalone clarity. |
Update history
No update history recorded yet.
Related work
-
Related To:
operator#1989
(confidence 95%)
The planned consolidated Ops documentation list motivated the best-practice formatting tweaks.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2748 docs: improve charm naming docs, with links to detailed guidance | charmcraft | merged | Docs PR #2748 merged (commit 0389aeb4): rewrote charm naming guidance in the charmcraft.yaml reference and manage-charms how-to, replacing inline best-practice notes with links to the Ops docs. Fixes #2582; relied on canonical/operator#2610. | |
| #1622 fix: reorganise charmcraft.yaml preprocessing | charmcraft | merged | Merged in #1622 (commit 7ce4182e): extensions now run first, charms with bases get a default part, and parts must be a dictionary. | |
| #2203 docs: copy best practices from Juju docs | charmcraft | merged | Merged PR #2203 as commit 5bf5edc6, adding reviewed Juju-derived best practices as hint admonitions, mainly to the charmcraft.yaml reference. | |
| #2299 docs: fix formatting issues | charmcraft | merged | Merged docs formatting fixes for local documentation builds in charmcraft#2299 via commit 5ffb80fe; two files changed (+3/-1). |