Charm Quality Ratings updates
Mark Shuttleworth
mark at ubuntu.com
Fri Oct 4 11:28:44 UTC 2013
I think we'll need the ability both to document the interface in a
particular charm, and to link to other charms interface docs from inside
such documentation.
So a charm which implements another charms interface exactly (perhaps by
importing code from that charm's codebase) could say "this is properly
documented over <here>". Another charm could say "we aspire to work with
the interface as defined <here> but here are some gotchas associated
with our implementation".
Mark
On 04/10/13 09:35, Nick Veitch wrote:
> 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
> <mailto: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>
> <mailto: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>
> <mailto: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
> <https://launchpad.net/%7Erharding>
> >>> > > @mitechie
> >>> > >
> >>> >
> >>>
> >>> --
> >>>
> >>> Rick Harding
> >>>
> >>> Cloud Engineering
> >>> https://launchpad.net/~rharding
> <https://launchpad.net/%7Erharding>
> >>> @mitechie
> >>>
> >>> --
> >>> Juju mailing list
> >>> Juju at lists.ubuntu.com <mailto:Juju at lists.ubuntu.com>
> <mailto: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 <mailto: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/251b5cb8/attachment.html>
More information about the Juju
mailing list