Where should deployment instructions for bundles exist?

[Matt Bruzek]

Hey Jorge,

When trying to deploy your bundle I was working exclusively from the
command line, I got your bundle from bzr branch and the package had just
*two* files, the README.md and the bundles.yaml.  I was not aware that the
Juju GUI had great instructions on how to deploy a bundle.

If the use case only *one* file (bundles.yaml). I would suggest putting a
short (one line?) comment with a link on where to get more information or a
one line message that you deploy with:  juju quickstart bundles.yaml or use
the Juju GUI "Import bundle" button.

I see your point for using the auto generation that we already have, but I
worry that is too long (25 lines in the GUI now).  The deploy instructions
go into how to install the bundle from the GUI, quickstart, and deployer.
At some point we risk tldr and I would not suggest adding a 25 line comment
to the bundles.yaml.

   - Matt Bruzek


On Wed, Mar 5, 2014 at 4:46 PM, Jorge O. Castro <jorge at ubuntu.com> wrote:

> I am working on submitting a mediawiki bundle:
>
> https://jujucharms.com/sidebar/search/bundle/~jorge/mediawiki-simple/5/mediawiki-simple/?text=mediawiki-simple
>
> In the GUI we provide a tab called Deploy which autogenerates
> deployment instructions. I love this because after editing individual
> deploy instructions in charms it's much nicer to have something that
> is not prone to human error and will always be correct.
>
> When Matt was reviewing my charm he noticed that I mention "After
> deployment you need to...", but the README has no "How do I deploy
> this bundle?" -- why would it, there's an entire autogenerated tab for
> that!
>
> But the README as a standalone file falls down. For obvious reasons I
> don't want to copy everything from the deployment tab into the README.
> On top of that when people want to share bundles there will be the
> usecase of people passing around just the bundle file without any of
> the corresponding documention:
>
> I thought of some ideas, so I thought I could bounce them off the list:
>
> - We could default to the Deploy tab in the GUI.
> - We could autogenerate a section on top of the README that points
> people more explicitly to the Deploy section.
>
> Also I think it would be worth investigating having the "export
> bundle" export everything the user will need instead of just the raw
> yaml file. Maybe zip up the bundle and cat the deploy instructions to
> the top of the README as part of exporting.
>
> We should also consider adding a comment to each bundle's exported
> file to the canonical location of it in the store in case I do get
> mailed a bundle with no instructions.
>
> Some food for thought!
>
> --
> Jorge Castro
> Canonical Ltd.
> http://juju.ubuntu.com/ - Automate your Cloud Infrastructure
>
> --
> 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/20140306/3dbcb6e6/attachment.html>