Add/clean up a bunch of help docs

Add/clean up a bunch of help docs

Help docs were primarily added around constraints, but I also tried to clean up related docs that I came across.

https://code.launchpad.net/~natefinch/juju-core/016-cons-docs/+merge/188455

(do not edit description out of merge proposal)

[natefinch, 2013-09-30 21:06:12]

Please take a look.

[fwereade, 2013-10-01 08:00:48]

LGTM (progress-not-perfection) but a fewcomments that might be useful.

Please also ping evilnickveitch and let him know you've done this -- we'll need
something similar for the public docs as well, I think, but perhaps he can
repurpose it.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/addmachine.go
File cmd/juju/addmachine.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/addmachine.go#newcode26
cmd/juju/addmachine.go:26: <container> can be one of lxc or kvm.
Except it can't, can it? Or have I missed all that?

https://codereview.appspot.com/14152043/diff/1/cmd/juju/addmachine.go#newcode36
cmd/juju/addmachine.go:36: juju add-machine lxc                  (starts a new
machine with an lxc container)
Does this work? I don't think it should. "lxc" is a (pseudo-)provider and should
require placement info -- "lxc:7" or whatever

https://codereview.appspot.com/14152043/diff/1/cmd/juju/bootstrap.go
File cmd/juju/bootstrap.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/bootstrap.go#newcode46
cmd/juju/bootstrap.go:46: will not  function properly.
They should function perfectly... by waiting until the state server's up, and
then executing, but not before.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/constraints.go
File cmd/juju/constraints.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/constraints.go#newcode43
cmd/juju/constraints.go:43: set-constraints mysql root-disk=99G  (all new
machines provisioned for mysql must have at least 99GB of disk space)
set-constraints wordpress mem=4G (all new wordpress machines can ignore the 8G
constraint above, and require only 4G)

?

https://codereview.appspot.com/14152043/diff/1/cmd/juju/deploy.go
File cmd/juju/deploy.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/deploy.go#newcode64
cmd/juju/deploy.go:64: juju deploy mysql -n 5 --constraints -n 5 mem=8G (deploy
5 instances of mysql with at least 8 GB of RAM each)
you've got two "-n 5"s

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go
File cmd/juju/help_topics.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go#newcod...
cmd/juju/help_topics.go:234: Constraints constraint the possible instances that
may be started by juju
s/constraint/constrain/

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go#newcod...
cmd/juju/help_topics.go:256: provisioned by the command.  Constraints specified
with --constraints will
This implies that we have add-unit --constraints. Do we? If so that's a massive
screwup.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/status.go
File cmd/juju/status.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/status.go#newcode49
cmd/juju/status.go:49: 
Nothing to do with status really -- maybe expand the explanation in bootstrap a
tiny bit?

[natefinch, 2013-10-01 14:38:55]

Made all the changes suggested, thanks for looking this over.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/addmachine.go
File cmd/juju/addmachine.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/addmachine.go#newcode26
cmd/juju/addmachine.go:26: <container> can be one of lxc or kvm.
On 2013/10/01 08:00:48, fwereade wrote:
> Except it can't, can it? Or have I missed all that?

Oops, you're right. I assumed it supported the same containers that
--constraints supports, but I see that there's code restricting it to lxc.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/addmachine.go#newcode36
cmd/juju/addmachine.go:36: juju add-machine lxc                  (starts a new
machine with an lxc container)
On 2013/10/01 08:00:48, fwereade wrote:
> Does this work? I don't think it should. "lxc" is a (pseudo-)provider and
should
> require placement info -- "lxc:7" or whatever

Nope, totally works, just tried it.  It'll start a new machine and put a
container on it.  I'm clarifying the help here to make that more obvious.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/bootstrap.go
File cmd/juju/bootstrap.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/bootstrap.go#newcode46
cmd/juju/bootstrap.go:46: will not  function properly.
On 2013/10/01 08:00:48, fwereade wrote:
> They should function perfectly... by waiting until the state server's up, and
> then executing, but not before.

Doh, you're right. I thought I'd seen commands failing because the state server
wasn't up, but maybe that was a different problem.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/constraints.go
File cmd/juju/constraints.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/constraints.go#newcode43
cmd/juju/constraints.go:43: set-constraints mysql root-disk=99G  (all new
machines provisioned for mysql must have at least 99GB of disk space)
On 2013/10/01 08:00:48, fwereade wrote:
> set-constraints wordpress mem=4G (all new wordpress machines can ignore the 8G
> constraint above, and require only 4G)
> 
> ?

yep, good idea

https://codereview.appspot.com/14152043/diff/1/cmd/juju/deploy.go
File cmd/juju/deploy.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/deploy.go#newcode64
cmd/juju/deploy.go:64: juju deploy mysql -n 5 --constraints -n 5 mem=8G (deploy
5 instances of mysql with at least 8 GB of RAM each)
On 2013/10/01 08:00:48, fwereade wrote:
> you've got two "-n 5"s

oops, thanks

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go
File cmd/juju/help_topics.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go#newcod...
cmd/juju/help_topics.go:234: Constraints constraint the possible instances that
may be started by juju
On 2013/10/01 08:00:48, fwereade wrote:
> s/constraint/constrain/

Yeah, saw this one seconds after I committed, figured there would be plenty of
other updates to roll in with it.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go#newcod...
cmd/juju/help_topics.go:256: provisioned by the command.  Constraints specified
with --constraints will
On 2013/10/01 08:00:48, fwereade wrote:
> This implies that we have add-unit --constraints. Do we? If so that's a
massive
> screwup.

We have deploy --constraints, which functions as juju set-constraints <service>
&& juju deploy <service>.  I actually assumed we had --constraints for add-unit,
and why not? It could function the same way as deploy does, as juju
set-constraints <service> && juju add-unit <service>.  

However, you're right that add-unit doesn't actually support --constraints. 
I'll remove the comment here and just leave deploy's help to explain how it's
constraints flag works.

https://codereview.appspot.com/14152043/diff/1/cmd/juju/status.go
File cmd/juju/status.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/status.go#newcode49
cmd/juju/status.go:49: 
On 2013/10/01 08:00:48, fwereade wrote:
> Nothing to do with status really -- maybe expand the explanation in bootstrap
a
> tiny bit?

You're right. I had mistakenly thought that status was the only thing that
actually waited for bootstrap to complete, but other things do as well. I'll
remove this and fix bootstrap's comment.

[fwereade, 2013-10-04 10:17:29]

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go
File cmd/juju/help_topics.go (right):

https://codereview.appspot.com/14152043/diff/1/cmd/juju/help_topics.go#newcod...
cmd/juju/help_topics.go:256: provisioned by the command.  Constraints specified
with --constraints will
On 2013/10/01 14:38:55, nate.finch wrote:
> On 2013/10/01 08:00:48, fwereade wrote:
> > This implies that we have add-unit --constraints. Do we? If so that's a
> massive
> > screwup.
> 
> We have deploy --constraints, which functions as juju set-constraints
<service>
> && juju deploy <service>.  I actually assumed we had --constraints for
add-unit,
> and why not? It could function the same way as deploy does, as juju
> set-constraints <service> && juju add-unit <service>.  
> 
> However, you're right that add-unit doesn't actually support --constraints. 
> I'll remove the comment here and just leave deploy's help to explain how it's
> constraints flag works.

The big reason why not is that juju is about *service* orchestration, and that
we would prefer to present a worldview in which there's nothing special about
any individual unit.

Individual unit placement messes with this a bit, it's true, but there's still
currently a hard line between juju doing things automatically at service level,
and a unit-level backdoor which is completely user-driven.