Juju Charm Best practices

Registered by Jorge Castro on 2012-04-30

Rationale:
How are people using charms? What kind of things should we recommend to people? How can we collect these best practices? As the Charm community grows there is a need to collect community knowledge. Then document and apply that knowledge on Charm best practices for others to build off of.

Goal:
Documentation and tools available for charmers to use in creation and submission of Charms.

Blueprint information

Status:
Started
Approver:
Antonio Rosales
Priority:
Medium
Drafter:
Ubuntu Server Team
Direction:
Approved
Assignee:
Mark Mims
Definition:
Approved
Series goal:
Accepted for quantal
Implementation:
Started
Milestone target:
milestone icon ubuntu-12.10
Started by
Kate Stewart on 2012-07-10

Related branches

Sprints

Whiteboard

* charm-tools -- charm proof should do everything it can to statically analyze and guide users
  * man pages are needed sorely
* charm-helpers -- Gather tools which are useful for sharing between many charms
  * python helpers have been proposed, but blocked up on needing to package some extra python deps
* Policy -- Policy is somewhat loose, just listed on https://juju.ubuntu.com/Charms
  * Should be useful information for writing charms, not just "rules"
  * Perhaps this should be moved into a versioned RST inside charm-tools?

charm best practices:

aka. "Charm tools all the things!"

time to be opinionated?
alternatively point to more example charms?

also juju best practices:
  this is really a charm best-practice for now... flag-bearing charms should include a _good_ readme.
  (see lp:charms/hadoop for an example)

BEST PRACTICES
==============

***** run charm proof before submitting *****
use charm helpers

---
User Stories:
* Simon is new to the Charm community and woud like to charm his newest web service. He consults the best practices documentation and reviews example charms, man pages, and downloads charm tools to help him as he charms his web service for inclusion in the Charm Store.

Assumptions:
* Extra Python deps are available for charm-helpers.

Test Plans:
* Gather feedback from new Charmers on how the charm tools and best practice documentation helped them in the creation of Charms. Possibly gather this data at Charm schools.

Release Note:
* Provide information on where to get charm tools and read Charm best practices.

(?)

Work Items

Work items:
[jorge] Pick better example charms, "flagbearer charms".: DONE
[jorge] Choose a single place for presenting flagbearer charms (charm browser?): POSTPONED
[jorge] Move rules and charm best practices into juju/docs.: DONE
[jorge] Add Maintainer field information to documentation. (thanks clint!): DONE
[jorge] Reach out to maintainers to get their maintainer field filled out.: DONE
[jorge] Add docs work items to patch pilot!: DONE
[jorge] pull "file bug" or "join the doc team" from other projects: POSTPONED
[jorge] Clarify documentention on what to expect when your using LXC and EC2. Cost, wait time, what you see, logs, downloading. "You should expect this to download 300 megs, etc." Here's a table of look here troubleshooting your LXC thing: DONE
[imbrandon] Reach out to maintainers to get their maintainer filled out.: DONE
[imbrandon] Put Doc instructions in the docs: http://askubuntu.com/q/52063 : POSTPONED
[mark-mims] (and individual maintainers!) clean up existing charms wrt best practices: DONE
[clint-fewbar] Comment and add links to docs in 'charm create' templates: POSTPONED
[clint-fewbar] juju in Debian! NOW!: DONE
[clint-fewbar] determine most likely maintainers based on bzr logs: DONE
[clint-fewbar] fix doc repos wrt (trunk, go, docs): DONE
[marcoceppi] tag:juju review on AU and SE network: DONE
[hazmat] incorporate output of charm proof into charm browser: DONE
[hazmat] clear out trunk docs for juju: DONE
[imbrandon] Clarify documentention on what to expect when your using LXC and EC2. Cost, wait time, what you see, logs, downloading. "You should expect this to download 300 megs, etc." Here's a table of look here troubleshooting your LXC thing.: POSTPONED
[hazmat] make juju report on initial lxc image downloads ?: POSTPONED
[clint-fewbar] make juju lxc use lxc networking instead of libvirt networking ?: POSTPONED

Dependency tree

* Blueprints in grey have been implemented.

This blueprint contains Public information 
Everyone can see this information.