docs: copy best practices from Juju docs
Metadata
Current evaluation
Merged PR #2203 as commit 5bf5edc6, adding reviewed Juju-derived best practices as hint admonitions, mainly to the charmcraft.yaml reference.
Resolution: closed resolved
Reason: The documentation changes were approved and merged in commit 5bf5edc6. They standardize Charmcraft best practices for consistent collection across the Charming ecosystem.
Evaluated by: mr-cal-bot
No scores available.
Issue body
This PR migrates best practices from [the Juju docs](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/charm/charm-development-best-practices/), where the best practice applies to Charmcraft. It is paired with a [similar PR for ops](https://github.com/canonical/operator/pull/1615).
The intention is to standardise best practices so that the docs can be scraped to collect best practices across Ops, Charmcraft, juju, and elsewhere in the charming ecosystem, to provide a comprehensive checklist for charmers.
My suggestion is for ReST we use:
```
.. admonition:: Best practice
:class: hint
Content goes here
```
This provides an admonition box that has the title "Best Practice", but is otherwise styled as a hint (David Wilding is working on putting a custom icon into the starter pack, to replace the ? icon that Furo defaults to).
The best practices here were selected in a review by @tmihoc and @dwilding and myself, although all problems with the suggested wording are my fault alone.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged PR #2203 as commit 5bf5edc6, adding reviewed Juju-derived best practices as hint admonitions, mainly to the charmcraft.yaml reference. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in canonical/charmcraft#2203 (5bf5edc6), adding approved Juju-derived best practices and hint admonitions, primarily to the charmcraft.yaml reference. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged after revisions narrowed scope to the charmcraft.yaml reference. The PR migrated approved best practices from Juju docs, standardized ReST admonition formatting, and integrated following three approvals. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged after revisions to focus changes on the charmcraft.yaml reference. Best practices were migrated from Juju docs, refined per team feedback, and integrated to standardize ecosystem documentation for automated scraping. |
Update history
No update history recorded yet.
Related work
-
Related To:
operator#1615
(confidence 100%)
Paired operator-framework PR applying the same best-practice documentation approach.
-
Related To:
canonical/charmcraft#2452
(confidence 95%)
Follow-up documentation change that tweaked the newly added best-practice blocks.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #2384 docs: copy note from Juju docs, tidy up container structure doc | charmcraft | merged | Merged in commit eb007460, adding Kubernetes storage-location guidance to charmcraft.yaml docs and restructuring the containers section; replaces #2380. | |
| #2135 Docs: Broken references to Juju | charmcraft | closed | Fixed by merged PR charmcraft#2136 in commit fe64df47, correcting six broken Juju documentation references across four files. | |
| #2452 docs: small tweaks to best practice blocks | charmcraft | merged | Merged in charmcraft#2452 via commit 655519ae, reclassifying two “manage charms” examples as a tip and making charmcraft.yaml best practices clearer standalone. | |
| #2136 docs: fix broken references to juju docs | charmcraft | merged | Merged in canonical/charmcraft#2136 (commit fe64df47), fixing six broken Juju documentation references across four docs files alongside juju/juju#18788 and #18790. |