doc/03-items.txt

   1 Items are just something that has to be done, like rebooting
   2 a server, finding an IP address, or installing some software.
   3
   4 It's very flexible what the items can be; make magic only cares
   5 that there is something to do, if it needs to be done in this
   6 case, what needs to be done first and if it's done yet.
   7
   8 If you want to automate any of the items though (and that's
   9 pretty much the point) these requirements have to be met
  10 for every item:
  11
  12
  13 * It's well defined.
  14
  15 Basically ask yourself, Can I automate this on it's own?
  16 If not, maybe it needs to be split up into multiple steps,
  17 or think of it more in terms of what you're trying to get
  18 done.
  19
  20 * Knowing what needs to happen first
  21
  22 You need to be clear what information you need to do the
  23 item, and what needs to happen before it does. e.g.
  24 before setting up the network on a system you probably
  25 need it's hostname, and need to have allocated an IP
  26 address.
  27
  28 * There is a clear point at which it finishes.
  29
  30 In almost every case, other items are going to be waiting
  31 until this item has finished, because it needs to rely on
  32 it having been done.  If you have a step called "Reboot the
  33 server", it's more likely what you really want is "Reboot
  34 the server and wait for it to come up again".
  35
  36 * You can tell if it worked or not
  37
  38 If you assume an item completed successfully without checking,
  39 other items that depend on it will run under the assumption
  40 everything is in a well known and consistent state, because
  41 everything before it ran correctly.  Blindly going ahead and
  42 doing stuff when things are already in a broken state will
  43 at best make it hard to debug, and at worst do damage.