Juju documentation

The Juju Charm Store

Juju includes a collection of what we call Charms that let you deploy whatever services you want in Juju. A collection of charms that are designed to work together is called a Bundle. Since charms and bundles are open and worked on by the community, they represent a distilled set of best practices for deploying these services. Both charms and bundles are included in what we collectively call The Charm Store.

Charm Store Process

This process is designed to allow prospective developers to have their charms reviewed and updated in the Charm Store in a timely manner that ensures peer reviews and quality.

Submitting a new Charm

  1. Install juju and charm-tools.
  2. Create a repository, something like mkdir -p ~/charms/precise, precise is the release code name for the release of Ubuntu you wish to target your charm at.
  3. If you haven't created your charm yet, you can use charm create ubuntu-package-name which will fill in some basic metadata info for you. You can check to see if it already exists at http://jujucharms.com/. Also make sure to check the list of open charms to see if anybody is already working on a charm for the service you want to work on. Bugs which have had no activity by the assignee for more than 30 days are fair game and should be unassigned.
  4. Once your charm is working and tested with any compatible charms, make sure it passes charm proof path/to/your/charm
  5. bzr init in your charm's root directory
  6. bzr add to add all files.
  7. bzr ci -m'Initial charm'
  8. bzr push lp:~your-launchpad-username/charms/precise/your-charms-name/trunk
  9. File a bug against charms at https://launchpad.net/charms/+filebug This is used to track the progress of your charm.
  10. Subscribe the charmers team by clicking "Subscribe someone else" on the right side of the launchpad page. This is important as it gets your charm in the review queue!

Your charm should then be looked at in a timely manner.

Submitting a fix to an existing Charm

  1. Grab the charm you want to fix, we'll use Nagios as an example: bzr branch lp:charms/precise/nagios
  2. Modify it to meet your needs.
  3. Commit your fixes bzr commit -m'Your changelog entry goes here'
  4. bzr push lp:~your-launchpad-username/charms/precise/nagios/fixed-charms-name
  5. Submit a merge proposal by going to your branch's code page: https://code.launchpad.net/~charmers/charms/precise/nagios/trunk and clicking "Propose for merging"
  6. In the merge proposal form select the charm's lp name: ~lp:charms/nagios
  7. For the reviewer field put the charmers team, this will get your code into the review queue!

Submitting bundles to the Charm Store

Refer to the Bundles page for instructions on how to create bundles of charms and submit them to the store.

Getting Help

Inspired by Bazaar's Patch Pilot programme there will be patch pilots in #juju who can help you get your patch accepted. Check the topic to see who's on duty. Still need help? Poke us on the mailing list ; if you're from an upstream project who wants more detailed help/tutoring, then contact Jorge Castro and we'd be more than happy to get a charm expert to help you out or help you run a Charm School.

Some notes:

  • Please respect that these people might have a few other charms in their queue already.
  • The package you have a question about might not necessarily be part of the patch pilot's area of expertise. They will still try to help you get your fix in and probably get you in touch with the 'right' people.

Reviewers

  1. Modify the topic in #juju to put yourself down as the reviewer for your shift.

  2. Check out the review queue and be responsive on IRC for user questions.

  3. Review the items in the queue. If the queue is caught up and not on fire, consider the following tasks:

  4. When your shift is over modify the topic in #juju to put ~charmers as the reviewer. (When no one is specifically assigned to review we just default to ~charmers).

  5. (Optional) Send a mail to the juju list summarizing your shift, new charms you might have promulgated or updated, issues that might have been raised by the review, or anything else you feel you should share with the community.

  6. Here's the Calendar for reviewing if you want to check what day you have.

Review Tips and Criteria

The goal is to welcome the contributor and help them have a good experience getting fixes into Ubuntu; your first response should be to thank them profusely. By making collaboration easier, we can hope to see more contributors and thus lighten the development workload on everyone.

  • Start your review by saying "Thanks", no matter what the outcome of the review is going to be.
  • If you recognise somebody you've worked with on IRC, thank them.
  • Run juju charm proof first. If there are serious problems with the charm based on the output of proof feel free to just stop the review there and tell them. You shouldn't promulgate a charm that has anything that’s a “WARNING” or more severe.
  • If the merge proposal or patch requires more work, encourage the contributor to join #juju and discuss the solution there.
  • Follow these instructions as well as you can.
  • If this is your first time patch piloting, you may feel more comfortable being a co-pilot your first few runs. Find a pilot in your timezone and reschedule your time to coincide with theirs.
  • Be super thorough, don’t be afraid to be firm with people. However, respect that charms are opinionated - just don’t be afraid to be opinionated yourself.
  • Please use the official Charm Store Policy document.
  • Use your best judgement.
  • Send a brief mail after your stint, to say what you did and how it worked out. If you have feedback on the review system or the process, speak up.
  • You're not obliged to deal with all the open patches. We appreciate what you do do.
  • You can prioritize whichever you think best achieves the goal of helping people enjoy getting things done in Juju. That might be the newest ones, neglected patches, easy patches, or those from new contributors. The Review Queue sorts by age.
  • If you are unfamiliar with the package, make sure you review everything you can, it's not necessarily your job to merge/promulgate it. If, after you did your review, you can get the contributor in touch with somebody who knows the codebase better, you already helped out a lot.
  • Consider blogging about a particularly nice contribution. This will not only make the contributor feel valued, but also inspire others with a good example of great work.
  • Encourage contributors to apply for ~charmers if you think they're ready.

Sponsorship is organized into

If something needs review, subscribe ~charmers.

You can see the currently pending requests at:

Updating the store

There are two methods of updating the store. One is promulgation of new charms, the other is updates to charms which already exist in the store:

New Charms

So the charm has passed all criteria and is ready to land in the store. Before you can promulgate, you’ll need to run the following commands. (This is only needed if you don’t have charm-tools >= 1.1 - This is being fixed in charm tools and will be landing soon).

bzr init lp:~charmers/charms/precise/<CHARM_NAME>/trunk
bzr push lp:~charmers/charms/precise/<CHARM_NAME>/trunk
               

Without this, LP will automatically stack on top of the user’s branch which will make it really really hard to delete from the store in the future. Now you can promulgate:

juju charm promulgate 

Updating existing charms in the store

Make sure you thank them profusely for fixing something or adding something even if they’re a Canonical employee!

Grab the charm from the store either with charm-tools or just bzr branch it.

juju charm get 

Note: Backwards compatibility is important! Any changes that would change the structure of the charm, data, configuration options, etc and doesn’t perform due diligence to make sure the charm does what it needs to, should be rejected.

Pay particular attention to interface providers that have extant clients/users.

Eventually, magic should take over this process and it should be done via jenkins and QA. Until then deploy the charm from local:, change config values, make relations, do what the charm needs to get setup. bzr merge the change, check the changes and make sure there are no obvious glaring things that break backwards compatibility (or just break the charm). Then juju upgrade the charm. Make sure nothing breaks in the service.

Other than that, just follow normal charm review process.

When you’re ready just bzr commit the merge, then bzr push :parent to update the store.

If you find anything that's lacking in the charm feel free to open bugs against that charm. This will help us curb the amount of charms to review during our audit.

Join Us!

We also need help reviewing and testing charms. The Charmers team is granted write access to the Charm Collection and charm-tools. If you'd like to join that group, here are some tips:

Upon getting involved with these activities, we'll probably ask you if you'd like to join charmers. If not, go ahead and apply for membership to the team, and send an email to the list letting us know about your reasons for wanting to be a member of charmers.