← Back to issue list

docs: copy best practices from Juju docs

View original Github issue

Metadata

Project
charmcraft
Number
#2203
Type
pull request
State
merged
Author
tonyandrewmeyer
Labels
—
Created
Updated
Closed

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.
75%
#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.
74%
#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.
72%
#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.
71%