Agreements around juju.Conn

[Gustavo Niemeyer]

We've had a conversation today on the channel about the interface of
juju.Conn, and agreed on a couple of different conventions that were a
bit flaky so far, and that will break some welcome consistency and
clarity to those areas:

1) We'll name command line subcommands that destroy resources as
destroy-foo. We already have destroy-environment and destroy-service,
and we should have destroy-relation, destroy-unit, etc. Of course,
that means maintaining the old names for compatibility reasons
wherever necessary. Besides bringing consistency, this solves some
naming issues we have at the moment regarding removal vs. polite
termination of resources: calling Remove methods on state still
removes the respective resources, but that's not what remove-unit does
anymore, for example.

2) juju.Conn should wrap command line functionality even when it's a
single line being called. We went back and forth a few times on when
we should have a method there or not, and it sounds fair to say that
the current implementation is pretty good. That said, it's not very
consistent in that we have certain features there, and others require
direct state manipulation, without a clear line. The agreement
establishes the line: if we have a subcommand with a given feature,
that subcommand should be available in similar fashion (not
necessarily the *exact* look & feel) in the juju.Conn implementation.
Besides clarity, this means we have a nice library API for people to
use juju from within Go, and also doubles as good documentation source
for people that want to see how to find their way in the juju code
base.

These give a more clear path forward regarding changes such as this:

    https://codereview.appspot.com/6700048/


gustavo @ http://niemeyer.net