docs for writing a basic charm

[hatched]

There doesn't appear to be anywhere which documents how to write a basic charm. I think it's quite important for charm authors to see what files are actually required to write a charm, what a proper structure for those files are, which fields are required, and how Juju interacts with them.

[pmahnke]

I think that's the goal of the [developer guide]( https://jujucharms.com/docs/stable/developer-getting-started) Is that not what you are expecting?

…

On 13 February 2017 at 01:12, Jeff Pihach ***@***.***> wrote: There doesn't appear to be anywhere which documents how to write a basic charm. I think it's quite important for charm authors to see what files are actually required to write a charm, what a proper structure for those files are, which fields are required, and how Juju interacts with them. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1651>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAa7gTv3n6e4XdHbdQ2mkQ7H-hKNcw_xks5rb63ygaJpZM4L-tEr> .

-- Peter Mahnke Head of Web development Canonical 0796 108 4362 peter.mahnke@canonical.com

[hatched]

No this guide requires users to understand the charm helpers, interfaces, layers, building, testing etc.

A charm is really only a collection of hook scripts which I find new people to Juju understand a lot easier. The guide I'm thinking of wouldn't even necessarily install a piece of software, it would simply illustrate which files are necessary, the structure of those files and how Juju interacts with them.

[evilnick]

That's the guide we used to have, sort of:
https://jujucharms.com/docs/1.25/authors-charm-components

The trouble is, nobody is supposed to write charms that way anymore. The developer section is getting a big overhaul anyway, though it may take some months to complete, so hopefully some of this will be addressed (e.g. I think even with layers et al, it is useful to know what files are needed and what they do)

[hatched]

I can just say that form my experience people have a much easier time understanding Juju and charms when you show them the raw files instead of obfuscating it behind a number of libraries and build tools.

[mitechie]

I've got this bug to file. To get started writing a charm you need to run charm create but that's not referenced anywhere. The getting started guide should start out with some notes on using create, build, and validating your charm did something imo.

[mitechie]

I've got a running list of notes/issues/confusion I hit as a first time reactive charm author in https://paper.dropbox.com/doc/Charm-Authoring-Feedback-3h1uUbXTP7sxoFJNk95qE that I'm working through and will update with bugs once I have gone through the process.

[evilnick]

I think we should beware of conflating 2 things here. I very much agree that the developer guide ought to

• explain the installation of tools (docs for charm-tools are also out of date, possibly charm tools itself is out of date)
• explain what a charm should look like/what the different parts do
• Do a guided walkthrough of creating a charm

It is going to end up more complicated (sorry @hatched) than the old method of just writing blobs of code for hooks, but it should be easier to follow than this.

[hatched]

While I totally understand that there are more advanced features for someone creating a real charm. For the absolute beginner I do not think that adding any complexity to get to a functional charm is a good idea. Lowering the barrier to entry should be very important and it can't get much simpler to write a charm than writing a few lines in an install hook, config.yaml, metadata.yaml.

[arosales]

100% agree on lowering the barrier to entry, and that is the aim of charm tools and layers. Although those tools would be new to a user it drastically helps them get a template and re-use code so they just focus on getting their app modeled with Juju.

@hatched brings up some good points in that it would be nice it include a cookbook simple, simple as possible, example say @ https://jujucharms.com/docs/stable/developer-layer-example that talk the user how to:

• charm create
• set layers ENV
• include basic layer
• build
• deploy
• modify

[hatched]

Here is a guide that was recently written by one of the community who found it daunting to get started writing charms:

https://github.com/erik78se/juju/wiki/The-hello-world-charm

[marcoceppi]

The problem with this guide is it doesn't set up the author for successfully writing charms. The hook file system is simple to grok but suffers when trying to model complexity past a single relationship. I think there can be improvements made to the getting started guide now. It's not a set of libraries it's just describing the nature of charm writing which is declarative set of states and responding to those state changes.

…

On Thu, Apr 20, 2017 at 4:20 PM Jeff Pihach ***@***.***> wrote: Here is a guide that was recently written by one of the community who found it daunting to get started writing charms: https://github.com/erik78se/juju/wiki/The-hello-world-charm — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1651 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAET1c5DNzIMfxiF-kqHdiPsWqmBVTa5ks5rx74EgaJpZM4L-tEr> .