Charm Quality Ratings updates

Fri Oct 4 08:35:04 UTC 2013

The issue which I think kicked this off is that charm authors wishing to
build against the interfaces offered by a specific charm have nowhere to go
to find out e.g. what is exposed by relation_set for a particular
interface, or what those values relate to.

We can include best practice guidelines for common interfaces (http say) in
the main documentation, but for specific stuff I currently see nowhere,
other than trawling through individual hook code, where that information
can be obtained (and even then it often isn't explained). It has to go with
the charm itself *somewhere*, doesn't it?

On Thu, Oct 3, 2013 at 7:21 PM, Gary Poster <gary.poster at canonical.com>wrote:

> On 10/03/2013 01:50 PM, Mark Shuttleworth wrote:
> >
> > Are we talking about documentation of the config (lightweight) or
> > documentation of the whole interface, for development purposes?
>
> Ah, thanks.  I was obviously speaking of the former, but after
> re-reading the start of the thread, it seems Jorge was discussing
> documentation of the whole interface.
>
> I think that whole-interface documentation should be outside of a charm,
> because mutiple charms can fulfill a given interface.  In that case,
> doing what Jorge seemed to be suggesting initially--putting it in the
> primary Juju docs--seems the right way within our current doc world.  We
> don't use YAML for that, so Nate's point is good.
>
> Gary
>
> >
> >
> > On 01/10/13 14:40, Gary Poster wrote:
> >> On 09/30/2013 09:47 AM, Nate Finch wrote:
> >>> I would recommend not making documentation an attribute in yaml.  That
> >>> puts strong pressure on writers to make their documentation extremely
> >>> short.  No one will want to type out a full page of documentation into
> a
> >>> yaml attribute.  Far better to make the documentation into a separate
> >>> file, to emphasize that you can write as much as you want (and more
> >>> documentation is almost always better).
> >> I'm not sure I agree with you here, but AFAIK the discussion is moot
> >> unless we want to rejigger most or all of our charms.  The config
> >> documentation is already in the YAML.
> >>
> >> Every config element in config.yaml has a description.  A majority of
> >> them have multi-line descriptions, which describe how to use them.
> >> Here's one of bunches of examples.
> >>
> >>   nagios_context:
> >>     description: |
> >>       Used by the nrpe-external-master subordinate charm.
> >>       A string that will be prepended to instance name to set the host
> name
> >>       in nagios. So for instance the hostname would be something like:
> >>           juju-myservice-0
> >>       If you are running multiple environments with the same services in
> >> them
> >>       this allows you to differentiate between them.
> >>     type: string
> >>     default: "juju"
> >>
> >> Gary
> >>
> >>>
> >>> On Mon, Sep 30, 2013 at 9:16 AM, Richard Harding
> >>> <rick.harding at canonical.com <mailto:rick.harding at canonical.com>>
> wrote:
> >>>
> >>>     Yes, we can do this. We currently support doing markdown rendering
> of a
> >>>     charm's readme in JS. Jorge, how are we looking to have users
> document
> >>>     their interfaces? As a description attribute in the yaml? Could
> that be
> >>>     easy to write out as markdown?
> >>>
> >>>     On Mon, 30 Sep 2013, Mark Shuttleworth wrote:
> >>>
> >>>     >
> >>>     > Are there good markdown renderers in JS? Should we aim for
> interface
> >>>     > documentation in MD?
> >>>     >
> >>>     > On 30/09/13 12:32, Richard Harding wrote:
> >>>     > > On Wed, 25 Sep 2013, Luca Paulina wrote:
> >>>     > >
> >>>     > >> On Wed, Sep 25, 2013 at 3:06 PM, Jorge O. Castro
> >>>     <jorge at ubuntu.com <mailto:jorge at ubuntu.com>> wrote:
> >>>     > >>
> >>>     > >>> Hi everyone,
> >>>     > >>>
> >>>     > >>> I'd like to revise the charm quality stuff a bit, mostly the
> >>>     ~charmers
> >>>     > >>> have captured that we would like to encourage folks to
> >>>     document the
> >>>     > >>> interfaces in their charms and I'd like to add that as a
> charm
> >>>     quality
> >>>     > >>> bullet item.
> >>>     > >>>
> >>>     > >>> In the past that just meant getting a +1 from some charmers
> and
> >>>     > >>> editing the docs, but now that we have a GUI I want to make
> >>>     sure we
> >>>     > >>> don't add things to the guidelines and not sync up with the
> >>>     GUI and
> >>>     > >>> design teams, so what would be the best way for me to drive
> that
> >>>     > >>> forward?
> >>>     > >> Thanks for the email Jorge, maybe we can find sometime to
> >>>     discuss it
> >>>     > >> tomorrow over a hangout. There is a need to revise the copy of
> >>>     the intro
> >>>     > >> paragraph as well, we should discuss that at the same time.
> >>>     > >>
> >>>     > >> Thanks,
> >>>     > >>
> >>>     > >> Luca
> >>>     > > Did this happen? To answer the first, question, a bit on
> >>>     charmworld to add
> >>>     > > the new QA item with the text and section to place it in will
> >>>     allow us to
> >>>     > > add it to the QA process. The Gui will then pick it up and
> >>>     adjust scores
> >>>     > > accordingly.
> >>>     > >
> >>>     > > --
> >>>     > >
> >>>     > > Rick Harding
> >>>     > >
> >>>     > > Cloud Engineering
> >>>     > > https://launchpad.net/~rharding
> >>>     > > @mitechie
> >>>     > >
> >>>     >
> >>>
> >>>     --
> >>>
> >>>     Rick Harding
> >>>
> >>>     Cloud Engineering
> >>>     https://launchpad.net/~rharding
> >>>     @mitechie
> >>>
> >>>     --
> >>>     Juju mailing list
> >>>     Juju at lists.ubuntu.com <mailto:Juju at lists.ubuntu.com>
> >>>     Modify settings or unsubscribe at:
> >>>     https://lists.ubuntu.com/mailman/listinfo/juju
> >>>
> >>>
> >>>
> >>>
> >>
> >
>
>
> --
> Juju mailing list
> Juju at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju/attachments/20131004/10588ebc/attachment-0001.html>