Issue 6922051: doc/draft: first attempts
Descriptiondoc/draft: first attempts
Note that these contain TODOs, questions, and vaguenesses; but they have
been reviewed by several people, and should be free of inaccuracies.
https://code.launchpad.net/~fwereade/juju-core/sketchy-documentation/+merge/139424
(do not edit description out of merge proposal)
Patch Set 1 #
Total comments: 112
Patch Set 2 : doc/draft: first attempts #Patch Set 3 : doc/draft: first attempts #Patch Set 4 : doc/draft: first attempts #
MessagesTotal messages: 12
Please take a look.
Sign in to reply to this message.
I haven't read the charms doc, the other two are LGTM. I trust you judgement regarding following my suggestions or not. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt File doc/draft/glossary.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode8 doc/draft/glossary.txt:8: makes no attempt to be comprehensive; just accurate, and opinionated. s/and opinionated// https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode76 doc/draft/glossary.txt:76: * maas (bare metal) [TODO: not implemented] TODO: work in progress perhaps? https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode77 doc/draft/glossary.txt:77: * local (lightweight containers on client machine) [TODO: not implemented] s/lightweight containers/LXC/? Not sure about this. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode78 doc/draft/glossary.txt:78: * openstack (many public and private clouds) [TODO: not implemented] TODO: work in progress perhaps? https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode120 doc/draft/glossary.txt:120: required, but can be omitted if AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY s/if/if the/ s/$/ environment variables/ https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode168 doc/draft/glossary.txt:168: here, but that may be a topic for a more detailed document.] Expose is provider specific, at least for now, for example MAAS doesn't have it. Not sure if it's in this document's scope. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt File doc/draft/lifecycles.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode4 doc/draft/lifecycles.txt:4: In juju, some things have "lifecycles". We sometimes refer to these things as I'd phrase it along these lines: | fundamental state entities have lifecycles. The entities are: X, Y Z. I believe the term is precise and we don't have to introduce more confusion. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode19 doc/draft/lifecycles.txt:19: * (removed) Is it a real lifecycle state or just a description of the entity disappearance in the system. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode35 doc/draft/lifecycles.txt:35: * When no principal units are assigned to it, it can be destroyed with s/it can be destroyed.*\./the user can call `juju destroy-machine`./ Since we are talking about state entities, mentioning destruction can be interpreted as destroying the entity in state, which is not the case. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode52 doc/draft/lifecycles.txt:52: Some mention about when units can leave a machine? https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode58 doc/draft/lifecycles.txt:58: for them in exactly the same What? :) https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode89 doc/draft/lifecycles.txt:89: endpoints can be added torelations. s/to/to / https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode93 doc/draft/lifecycles.txt:93: (Contentious? I *think* python blocks service removal until relations are d https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:203: (Oh: it shoud be noted explicitly that the PA is responsible for provisioning Delete the parenthesis, keep the remark. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:215: We use the mgo/txn package for easy multi-document transactions against MongoDB. s/easy// https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:216: Without this, it would be very difficult to enforce the various conditions The package is used. Keep it positive. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:223: At the moment, the only type whose lifecycle has been implemented approximately s/the/this/ It's "the" from your perspective as a writer, but it's "this" for the reader. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:227: we haven't started looking at service desctruction yet, so this is maybe not so destruction https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:230: So -- IMO, none of this has yet been implemented to an adequate standard, and s/So -- IMO,// From this point forward, you started using "I" instead of "we". I think we should keep it impersonal and generic. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:231: we're not short of detailed work to do. I'm currently focused on subordinates, We are or The current focus demands https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:239: especially considering it'll be easiest, but I'm not even going to think about s/, .*$// https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:249: *have* to worry about it yet I'm ignoring it. Avoid pronoun.
Sign in to reply to this message.
Very good work, thank you William. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt File doc/draft/glossary.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode77 doc/draft/glossary.txt:77: * local (lightweight containers on client machine) [TODO: not implemented] "local containers based on LXC" instead of "lightweight containers". Status is WIP or Paused. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode120 doc/draft/glossary.txt:120: required, but can be omitted if AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY +1 https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt File doc/draft/lifecycles.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode56 doc/draft/lifecycles.txt:56: * While a principal unit is alive, it can be assigned to machines and can have "assigned to a machine" https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:102: service.) I'm understanding the motivation behind it, it's logical. But somehow I don't feel good with the responsibility of two different agents for the removal. Will think more about it. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:230: So -- IMO, none of this has yet been implemented to an adequate standard, and No personal perspective here (and anywhere else).
Sign in to reply to this message.
Great stuff - really comprehensive and in-depth, 10x! LGTM - I've added some comments. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt File doc/draft/charms-in-action.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:71: The most important consequence of this is that it is a mistake to conflate the Just a suggestion - to make it a bit simpler, "mix up" (or "confuse") instead of "conflate". https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt File doc/draft/glossary.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode56 doc/draft/glossary.txt:56: A `machine` is a compute resource on which components of juju, and of the s/compute/computing/? https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode72 doc/draft/glossary.txt:72: An `environment provider` mediates between juju and the substrate on which an "substrate" nice! I can see the Culture peeking behind:) https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode176 doc/draft/glossary.txt:176: ok for defaults to change, but (eg) a string cannot become an integer). s/eg/e.g./ https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode189 doc/draft/glossary.txt:189: and crossgrades to entirely different charms, but priority/agreement is unclear.] crossgrades.. or even transgrades! https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode228 doc/draft/glossary.txt:228: can fulfil some role over some interface. ISTM this description is still not very clear. An example or scope of application will help though. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode288 doc/draft/glossary.txt:288: How about peer relation's scope? And in general, when there are so many relation types, maybe it's better to distinguish them like this: a `charm relation`'s `scope` (or in quotes). This moves the focus at the right place, rather than being ambiguous at first glance. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode329 doc/draft/glossary.txt:329: at the service level, a user can ensure that her workloads are only run on her? why not their https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt File doc/draft/lifecycles.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode34 doc/draft/lifecycles.txt:34: * While it is Alive, principal units can be assigned to it. with `juju add-unit` ? https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode57 doc/draft/lifecycles.txt:57: subordinate units added. When subordinate units are added, it is responsible with `juju <what>` ? https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:109: scope. how is this related to `juju add-relation`? https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:170: * destroying a container relation destroys all subordinates in the relation container relation? =local? https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:216: Without this, it would be very difficult to enforce the various conditions Why without it? Is it going away or under threat of doing so? :) https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:223: At the moment, the only type whose lifecycle has been implemented approximately On 2012/12/12 12:55:13, aram wrote: > s/the/this/ > > It's "the" from your perspective as a writer, but it's "this" for the reader. Or just "currently" / "presently" https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:248: the same problem for subordinate units wrt their principal), but since we don't s/wrt/with/
Sign in to reply to this message.
Very nice docs, thanks man. Review for charms-in-action: https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt File doc/draft/charms-in-action.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:14: by juju at particular times, and thereby cause the charm to run a unit of its Doesn't sound entirely right. The hooks don't cause the charm to run a unit of the service. It's the opposite: a unit of the service, when running, causes hooks of the charm to be run. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:25: useful guarantees can and will be made. All such guarantees come with the caveat s/can and will/are/ https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:34: Hooks should be idempotent, because they can fail, and may need to be re-executed I'd phrase that more lightly as """ Hooks ideally should be idempotent, so that they can fail and be re-executed from scratch without trouble. """ https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:55: information or advice before signalling the error. Well said. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:64: * A charm is deployed into a directory, managed by git, that is entirely s/managed by git// It's an implementation detail which shouldn't matter. People will think they have to understand git or something when they see that here, and will ask "Oh, but why not X!?", and raise other feelings that are really unrelated to what we're doing there. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:71: The most important consequence of this is that it is a mistake to conflate the On 2012/12/12 19:04:34, dimitern wrote: > Just a suggestion - to make it a bit simpler, "mix up" (or "confuse") instead of > "conflate". "conflate" sounds like a simple word. :-) https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:79: back into the charm of its own accord. That seems to be going into unnecessary territory. The system can really go to whatever state it wants after the charm has run. You've already declared the real constraint above, so this paragraph seems unnecessary and confusing. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:241: Relations in depth The docs below are great. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:262: only observe each other; peers observe all peers which are not themselves.) I'd put that a bit more extensively for clarity: each provider unit observes all requirer units; each requirer unit observes all provider unit. Each peer unit observes every other peer unit. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:282: relation (those returned by calling relation-list without arguments), but This sounds like a bad advice if we're claiming this is the most basic use. The most common use is for relation-get to be used without specifying the relation unit, and without using relation-list, which will obtain information about "the remote unit". The concept wasn't mentioned here, and it jumped straight into relation-list matters. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:287: * Otherwise, don't use relation-get. Nothing above seems to have mentioned the fact that relation-get/set have some form of data lifecycle associated with the hook execution. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:290: use of relation-set to the relation-joined hook. This is by no means required, This sounds like saying "don't do more than you have to", which is a fine advice, but orthogonal to the point being debated here. Lots of relation-changed hooks use relation-set, and it's useful, simple, and works. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:293: repeated executions of relation-changed hooks by counterpart units. Also doesn't sound like sensible advice. One can have no relation-joined hook whatsoever, and put everything on relation-changed, and that would also reduce the chances of re-execution. Even if the two scripts exist, there's no guarantee that it'll improve the timing in any way. Not anymore than recommending people write shorter scripts, for example, to reduce the chances of the other side picking up two changes independently. Am I on crack here?
Sign in to reply to this message.
On lifecycles.txt: https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt File doc/draft/lifecycles.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode6 doc/draft/lifecycles.txt:6: can connect to state", ie unit and machine agents (and then presumably, one day, Please let's not make the confusion official. :-) Entities are relations, units, services, and machines, as pointed out below. Agents can run to implement the actions of an entity, since the entity itself is of course an abstract concept. The *agent* is not "an entity" by itself. The document should clarify that rather than reinforcing the loose use of these terms. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode19 doc/draft/lifecycles.txt:19: * (removed) On 2012/12/12 12:55:13, aram wrote: > Is it a real lifecycle state or just a description of the entity disappearance > in the system. I'd say it is *not* a life state. The life state in those cases is still Dead. What happens is that the entity is not in the database anymore, despite the fact its state is Dead. We can word it as: * Dead and in the database * Dead and removed from the database to be clear. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode26 doc/draft/lifecycles.txt:26: ...and just about all else is tricky detail, that is worth examining from a few Starting an explanation by saying it's tricky creates an understanding wall without adding any useful information. I'd put that more optimistically as: """ There are two ...: ... Then, the way the lifecycle shifts occur varies with the entity, as follows. """ https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode34 doc/draft/lifecycles.txt:34: * While it is Alive, principal units can be assigned to it. On 2012/12/12 19:04:34, dimitern wrote: > with `juju add-unit` ? In many ways: juju add-unit, juju deploy, etc. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode45 doc/draft/lifecycles.txt:45: * When the Provisioning Agent (PA) observes that the machine has become Dead, There's no provisioning agent anymore. We have a provisioner that runs within a machine agent. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode47 doc/draft/lifecycles.txt:47: machine object from state. (Future uncertainty: should the PA provision an s/PA/provisioner/ https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode51 doc/draft/lifecycles.txt:51: allowed to continue to shut down cleanly as they would usually do. Maybe.) Good question. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode58 doc/draft/lifecycles.txt:58: for them in exactly the same s/exactly the same/similar/, if I can read your mind. ;-) https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode87 doc/draft/lifecycles.txt:87: removed, if you want to consider that a life state). Again, this is a good chance to solving the ambiguities, rather than reinforcing them. What happens is that services become Dead and are removed from the database as a single atomic operation, so they are not an exception to any of what was stated previously. The above sentence may be dropped with this perspective, or reworded as: * In addition, services become Dead and are removed as a single atomic operation. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:107: * A relation, like a service, has no corresponding agent and cannot be Dead. We can also use the same perspective: the relation becomes Dead and is removed as a single atomic operation. This simplifies understanding (the above sentence makes it feel like relations never die). https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:113: from state immediately rather than being set to Dying. "... it will become Dead and be removed from state as an atomic operation rather than ..." https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:197: * detecting its machine's Dying state, and setting it to Dead. Should wait for all units to evacuate before that. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:203: (Oh: it shoud be noted explicitly that the PA is responsible for provisioning s/PA/provisioner/ https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:265: ...*and*: FWIW, these last two paragraphs have a feeling of "OMG this is all so hard there's so much to do!". It'd be nice to have a less sentimental view on the issues that focused on what has to be done, and an analytical view of cheap wins we can have on the path to it, in a style similar to the rest of the document. Many of those issues have already been debated, and we can be more constraining and require more manual action on the way to a perfect implementation.
Sign in to reply to this message.
Please take a look. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt File doc/draft/charms-in-action.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:14: by juju at particular times, and thereby cause the charm to run a unit of its On 2012/12/14 18:40:56, niemeyer wrote: > Doesn't sound entirely right. The hooks don't cause the charm to run a unit of > the service. It's the opposite: a unit of the service, when running, causes > hooks of the charm to be run. Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:25: useful guarantees can and will be made. All such guarantees come with the caveat On 2012/12/14 18:40:56, niemeyer wrote: > s/can and will/are/ Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:64: * A charm is deployed into a directory, managed by git, that is entirely On 2012/12/14 18:40:56, niemeyer wrote: > s/managed by git// > > It's an implementation detail which shouldn't matter. People will think they > have to understand git or something when they see that here, and will ask "Oh, > but why not X!?", and raise other feelings that are really unrelated to what > we're doing there. Depends who I'm talking to. I imagine that a charm author will find the fact that it's managed by git to be genuinely useful -- it's more-or-less a complete record of the charm's operation, and could I think be valuable when trying to figure out weird situations. I'll drop mention here and add a note in the debugging section. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:71: The most important consequence of this is that it is a mistake to conflate the On 2012/12/14 18:40:56, niemeyer wrote: > On 2012/12/12 19:04:34, dimitern wrote: > > Just a suggestion - to make it a bit simpler, "mix up" (or "confuse") instead > of > > "conflate". > > "conflate" sounds like a simple word. :-) I'm sticking with conflate then :) https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:79: back into the charm of its own accord. On 2012/12/14 18:40:56, niemeyer wrote: > That seems to be going into unnecessary territory. The system can really go to > whatever state it wants after the charm has run. You've already declared the > real constraint above, so this paragraph seems unnecessary and confusing. I think it's important to stress the fact that there's no safe way to feed information back into the charm from outside juju; it also introduces the following TODO quite helpfully. Rephrased. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:241: Relations in depth On 2012/12/14 18:40:56, niemeyer wrote: > The docs below are great. :D https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:262: only observe each other; peers observe all peers which are not themselves.) On 2012/12/14 18:40:56, niemeyer wrote: > I'd put that a bit more extensively for clarity: each provider unit observes all > requirer units; each requirer unit observes all provider unit. Each peer unit > observes every other peer unit. Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:282: relation (those returned by calling relation-list without arguments), but On 2012/12/14 18:40:56, niemeyer wrote: > This sounds like a bad advice if we're claiming this is the most basic use. The > most common use is for relation-get to be used without specifying the relation > unit, and without using relation-list, which will obtain information about "the > remote unit". The concept wasn't mentioned here, and it jumped straight into > relation-list matters. Ha, yeah, that was... erm, "so obvious I didn't need to mention it". https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:287: * Otherwise, don't use relation-get. On 2012/12/14 18:40:56, niemeyer wrote: > Nothing above seems to have mentioned the fact that relation-get/set have some > form of data lifecycle associated with the hook execution. That's mentioned some way up when I talk about the execution environment. https://codereview.appspot.com/6922051/diff/1/doc/draft/charms-in-action.txt#... doc/draft/charms-in-action.txt:293: repeated executions of relation-changed hooks by counterpart units. On 2012/12/14 18:40:56, niemeyer wrote: > Also doesn't sound like sensible advice. One can have no relation-joined hook > whatsoever, and put everything on relation-changed, and that would also reduce > the chances of re-execution. Even if the two scripts exist, there's no guarantee > that it'll improve the timing in any way. Not anymore than recommending people > write shorter scripts, for example, to reduce the chances of the other side > picking up two changes independently. > > Am I on crack here? No, you're not, your criticism is well taken. I've rewritten this section and hope it will find favour :). https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt File doc/draft/glossary.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode8 doc/draft/glossary.txt:8: makes no attempt to be comprehensive; just accurate, and opinionated. On 2012/12/12 12:55:13, aram wrote: > s/and opinionated// Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode56 doc/draft/glossary.txt:56: A `machine` is a compute resource on which components of juju, and of the On 2012/12/12 19:04:34, dimitern wrote: > s/compute/computing/? We've generally been using the term "compute resource", but highly scientific googlefighting declares "computing resource" the winner. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode72 doc/draft/glossary.txt:72: An `environment provider` mediates between juju and the substrate on which an On 2012/12/12 19:04:34, dimitern wrote: > "substrate" nice! I can see the Culture peeking behind:) ;) https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode76 doc/draft/glossary.txt:76: * maas (bare metal) [TODO: not implemented] On 2012/12/12 12:55:13, aram wrote: > TODO: work in progress > > perhaps? Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode77 doc/draft/glossary.txt:77: * local (lightweight containers on client machine) [TODO: not implemented] On 2012/12/12 14:01:21, TheMue wrote: > "local containers based on LXC" instead of "lightweight containers". Status is > WIP or Paused. I think I like "LXC containers" https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode78 doc/draft/glossary.txt:78: * openstack (many public and private clouds) [TODO: not implemented] On 2012/12/12 12:55:13, aram wrote: > TODO: work in progress > > perhaps? Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode120 doc/draft/glossary.txt:120: required, but can be omitted if AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY On 2012/12/12 14:01:21, TheMue wrote: > +1 Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode168 doc/draft/glossary.txt:168: here, but that may be a topic for a more detailed document.] On 2012/12/12 12:55:13, aram wrote: > Expose is provider specific, at least for now, for example MAAS doesn't have it. > Not sure if it's in this document's scope. Mentioned in passing. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode176 doc/draft/glossary.txt:176: ok for defaults to change, but (eg) a string cannot become an integer). On 2012/12/12 19:04:34, dimitern wrote: > s/eg/e.g./ Bleh, if you prefer :). https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode189 doc/draft/glossary.txt:189: and crossgrades to entirely different charms, but priority/agreement is unclear.] On 2012/12/12 19:04:34, dimitern wrote: > crossgrades.. or even transgrades! lateral hypergrades! https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode228 doc/draft/glossary.txt:228: can fulfil some role over some interface. On 2012/12/12 19:04:34, dimitern wrote: > ISTM this description is still not very clear. An example or scope of > application will help though. Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode288 doc/draft/glossary.txt:288: On 2012/12/12 19:04:34, dimitern wrote: > How about peer relation's scope? > > And in general, when there are so many relation types, maybe it's better to > distinguish them like this: a `charm relation`'s `scope` (or in quotes). This > moves the focus at the right place, rather than being ambiguous at first glance. Addressed, I think -- but I'm trying to reserve ``s for first-introduction-of-terms. https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode329 doc/draft/glossary.txt:329: at the service level, a user can ensure that her workloads are only run on On 2012/12/12 19:04:34, dimitern wrote: > her? why not their Because "their" is kinda stuffy and lumpen, and "his" is an insidious symbol of an oppressive patriarchy ;). https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt File doc/draft/lifecycles.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode4 doc/draft/lifecycles.txt:4: In juju, some things have "lifecycles". We sometimes refer to these things as On 2012/12/12 12:55:13, aram wrote: > I'd phrase it along these lines: > > | fundamental state entities have lifecycles. The entities are: X, Y Z. > > I believe the term is precise and we don't have to introduce more confusion. OK, fantastic -- be warned that I may start agitating at some stage for an s/EntityName/AgentName/ across the codebase, because that's what those names really are. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode6 doc/draft/lifecycles.txt:6: can connect to state", ie unit and machine agents (and then presumably, one day, On 2012/12/14 19:55:35, niemeyer wrote: > Please let's not make the confusion official. :-) > > Entities are relations, units, services, and machines, as pointed out below. > Agents can run to implement the actions of an entity, since the entity itself is > of course an abstract concept. The *agent* is not "an entity" by itself. > > The document should clarify that rather than reinforcing the loose use of these > terms. Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode19 doc/draft/lifecycles.txt:19: * (removed) On 2012/12/14 19:55:35, niemeyer wrote: > On 2012/12/12 12:55:13, aram wrote: > > Is it a real lifecycle state or just a description of the entity disappearance > > in the system. > > I'd say it is *not* a life state. The life state in those cases is still Dead. > What happens is that the entity is not in the database anymore, despite the fact > its state is Dead. > > We can word it as: > > * Dead and in the database > * Dead and removed from the database > > to be clear. Done, roughly. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode35 doc/draft/lifecycles.txt:35: * When no principal units are assigned to it, it can be destroyed with On 2012/12/12 12:55:13, aram wrote: > s/it can be destroyed.*\./the user can call `juju destroy-machine`./ > > Since we are talking about state entities, mentioning destruction can be > interpreted as destroying the entity in state, which is not the case. Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode45 doc/draft/lifecycles.txt:45: * When the Provisioning Agent (PA) observes that the machine has become Dead, On 2012/12/14 19:55:35, niemeyer wrote: > There's no provisioning agent anymore. We have a provisioner that runs within a > machine agent. /me hangs head in shame https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode47 doc/draft/lifecycles.txt:47: machine object from state. (Future uncertainty: should the PA provision an On 2012/12/14 19:55:35, niemeyer wrote: > s/PA/provisioner/ Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode52 doc/draft/lifecycles.txt:52: On 2012/12/12 12:55:13, aram wrote: > Some mention about when units can leave a machine? I think it's implicit in the Dying requirement -- can you see a nice way to work it in? https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode56 doc/draft/lifecycles.txt:56: * While a principal unit is alive, it can be assigned to machines and can have On 2012/12/12 14:01:21, TheMue wrote: > "assigned to a machine" Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode57 doc/draft/lifecycles.txt:57: subordinate units added. When subordinate units are added, it is responsible On 2012/12/12 19:04:34, dimitern wrote: > with `juju <what>` ? complicated; covered in charms-in-action.txt https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode58 doc/draft/lifecycles.txt:58: for them in exactly the same On 2012/12/14 19:55:35, niemeyer wrote: > s/exactly the same/similar/, if I can read your mind. ;-) Ha. Removed. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode87 doc/draft/lifecycles.txt:87: removed, if you want to consider that a life state). On 2012/12/14 19:55:35, niemeyer wrote: > Again, this is a good chance to solving the ambiguities, rather than reinforcing > them. What happens is that services become Dead and are removed from the > database as a single atomic operation, so they are not an exception to any of > what was stated previously. > > The above sentence may be dropped with this perspective, or reworded as: > > * In addition, services become Dead and are removed as a single atomic > operation. Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode89 doc/draft/lifecycles.txt:89: endpoints can be added torelations. On 2012/12/12 12:55:13, aram wrote: > s/to/to / Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcode93 doc/draft/lifecycles.txt:93: (Contentious? I *think* python blocks service removal until relations are On 2012/12/12 12:55:13, aram wrote: > d Not sure -- is anyone else going to weigh in on the Right Thing to do here? This feels like a bit of an aggressive UI change, and I think we might want to reconsider. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:109: scope. On 2012/12/12 19:04:34, dimitern wrote: > how is this related to `juju add-relation`? It's not, really, except rather indirectly -- I've been trying to keep the focus on the transitions from Alive->Dying->Dead. I *think* the various commands are best addressed in a separate document, focused on the command line, that includes only a minimal treatment of lifecycles. Could be wrong though... https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:113: from state immediately rather than being set to Dying. On 2012/12/14 19:55:35, niemeyer wrote: > "... it will become Dead and be removed from state as an atomic operation rather > than ..." Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:113: from state immediately rather than being set to Dying. On 2012/12/14 19:55:35, niemeyer wrote: > "... it will become Dead and be removed from state as an atomic operation rather > than ..." Done. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:170: * destroying a container relation destroys all subordinates in the relation On 2012/12/12 19:04:34, dimitern wrote: > container relation? =local? Oh, blast. I think I mix terminology freely in this CL. Gah. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:197: * detecting its machine's Dying state, and setting it to Dead. On 2012/12/14 19:55:35, niemeyer wrote: > Should wait for all units to evacuate before that. Covered extensively in the discussion of machines, don't think I need to reiterate here. https://codereview.appspot.com/6922051/diff/1/doc/draft/lifecycles.txt#newcod... doc/draft/lifecycles.txt:203: (Oh: it shoud be noted explicitly that the PA is responsible for provisioning On 2012/12/14 19:55:35, niemeyer wrote: > s/PA/provisioner/ Done.
Sign in to reply to this message.
https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt File doc/draft/glossary.txt (right): https://codereview.appspot.com/6922051/diff/1/doc/draft/glossary.txt#newcode176 doc/draft/glossary.txt:176: ok for defaults to change, but (eg) a string cannot become an integer). On 2012/12/20 21:31:29, fwereade wrote: > On 2012/12/12 19:04:34, dimitern wrote: > > s/eg/e.g./ > > Bleh, if you prefer :). better still to avoid the abbreviation and use "for example".
Sign in to reply to this message.
Please take a look.
Sign in to reply to this message.
I'm pretty sure this already has 2 LGTM so it is ready to land. But I'm happy enough with the text as is. We can tweak it if we find better ways to say it in the future.
Sign in to reply to this message.
On 2013/01/04 08:20:43, jameinel wrote: > I'm pretty sure this already has 2 LGTM so it is ready to land. But I'm happy > enough with the text as is. We can tweak it if we find better ways to say it in > the future. It's had a few notable changes since those LGTMs -- but, yeah, I guess so. Thanks :).
Sign in to reply to this message.
*** Submitted: doc/draft: first attempts Note that these contain TODOs, questions, and vaguenesses; but they have been reviewed by several people, and should be free of inaccuracies. R=aram, TheMue, dimitern, niemeyer, rog, jameinel CC= https://codereview.appspot.com/6922051
Sign in to reply to this message.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
