doc: rudimentary developer docs for state

doc: rudimentary developer docs for state

This has been dashed off without deep thought; I'm sure there are bits
missing. If you, dear reader, are not especially familiar with the nuts
and bolts of state, I would particularly appreciate your input.

https://code.launchpad.net/~fwereade/juju-core/doc-hacking-state/+merge/154413

(do not edit description out of merge proposal)

[fwereade, 2013-03-20 15:41:32]

Please take a look.

[rog, 2013-03-20 16:34:11]

this is great, thanks!
a few thoughts below.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt
File doc/hacking-state.txt (right):

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode51
doc/hacking-state.txt:51: * transactions will complete, or not run at all.
perhaps add: all the asserts are checked, *then* all the operations take place ?

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode74
doc/hacking-state.txt:74: that fail in the following situations:
the double-negative here doesn't help understanding i think.
perhaps:

... a list of operations that assert that:

- the transaction still needs to be applied
- the transaction is actively valid.
- facts on which the transaction list's form depends remain true.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode88
doc/hacking-state.txt:88: state and try to run it again.
this is quite a sentence! it could perhaps do with a little expansion.

("an assertion of the third kind"... http://www.youtube.com/watch?v=cwGQKsFTK9Q
:-))

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode125
doc/hacking-state.txt:125: transactions and refcounts
s/refcounts/reference counting/ ?
this is an english document after all.
i generally think "reference count" (or "ref count") is better than "refcount"
too.

[jameinel, 2013-03-21 09:34:13]

LGTM.

I have some comments, but I think this is more helpful than not to have around
to point people to.

Thanks for writing it.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt
File doc/hacking-state.txt (right):

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode65
doc/hacking-state.txt:65: should return immediately without error.
Is this something like "requests should be idempotent, if it appears they have
already been run, return immediately without error".
?

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode123
doc/hacking-state.txt:123: before you embark on further work in this area.
While I appreciate the feeling here, I'm guessing this could be written without
the specific emotion. :)

[dimitern, 2013-03-21 09:53:22]

LGTM, thanks for writing this, it's very useful information.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt
File doc/hacking-state.txt (right):

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode108
doc/hacking-state.txt:108: EntityWatcher in that it sends whole *Settings~s down
the channel
*Settings~s? What is this?

[fwereade, 2013-03-22 10:21:42]

*** Submitted:

doc: rudimentary developer docs for state

This has been dashed off without deep thought; I'm sure there are bits
missing. If you, dear reader, are not especially familiar with the nuts
and bolts of state, I would particularly appreciate your input.

R=rog, jameinel, dimitern
CC=
https://codereview.appspot.com/7631046

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt
File doc/hacking-state.txt (right):

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode51
doc/hacking-state.txt:51: * transactions will complete, or not run at all.
On 2013/03/20 16:34:11, rog wrote:
> perhaps add: all the asserts are checked, *then* all the operations take place
?

Done something similar.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode65
doc/hacking-state.txt:65: should return immediately without error.
On 2013/03/21 09:34:14, jameinel wrote:
> Is this something like "requests should be idempotent, if it appears they have
> already been run, return immediately without error".
> ?

I'm reluctant to say that because I fear it would easily be misread as
"transactions should be idempotent", which is not necessarily good advice.
Keeping as is for now -- the point is to encourage people to "consider the
impact", because I think the implications may differ across cases.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode74
doc/hacking-state.txt:74: that fail in the following situations:
On 2013/03/20 16:34:11, rog wrote:
> the double-negative here doesn't help understanding i think.
> perhaps:
> 
> ... a list of operations that assert that:
> 
> - the transaction still needs to be applied
> - the transaction is actively valid.
> - facts on which the transaction list's form depends remain true.

Done.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode88
doc/hacking-state.txt:88: state and try to run it again.
On 2013/03/20 16:34:11, rog wrote:
> this is quite a sentence! it could perhaps do with a little expansion.
> 
> ("an assertion of the third kind"...
http://www.youtube.com/watch?v=cwGQKsFTK9Q
> :-))

Clarified a little, I hope.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode108
doc/hacking-state.txt:108: EntityWatcher in that it sends whole *Settings~s down
the channel
On 2013/03/21 09:53:23, dimitern wrote:
> *Settings~s? What is this?

I've used, and seen used, `~s" used as a plural suffix for strings that are
confusing when otherwise made plural. But I'll rework it.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode123
doc/hacking-state.txt:123: before you embark on further work in this area.
On 2013/03/21 09:34:14, jameinel wrote:
> While I appreciate the feeling here, I'm guessing this could be written
without
> the specific emotion. :)

Heh. Done.

https://codereview.appspot.com/7631046/diff/1/doc/hacking-state.txt#newcode125
doc/hacking-state.txt:125: transactions and refcounts
On 2013/03/20 16:34:11, rog wrote:
> s/refcounts/reference counting/ ?
> this is an english document after all.
> i generally think "reference count" (or "ref count") is better than "refcount"
> too.

Disagree, but don't care that much. Done.