discussion about encapsulation in puppet

puppet.md

@@ -11,6 +11,24 @@
 -   Do not use `->` and `~>`, use `require`, `notify` or `subscribe`
     instead.
 -   *Never* use `<-` or `<~`. (Lint will stop you, anyway.)
+-   Don't break encapsulation. In particular, a resource within one module
+    not create a dependency (require or notify) to a resource deep within
+    another. For example, File[/etc/nginx/sites-available/foo] from module
+    foo should *not* directly notify Service[nginx] in module nginx.
+    Instead consider these options:
+  -   use the anchor pattern to ensure dependencies are passed up and down
+      the include hierarchy correctly, and specifiy the dependency at the
+      top level. In our example, this means we would have:
+
+    class {'foo': notify => Class['nginx']}
+    class {'nginx':}
+
+  -   create a defined type within one module which other modules can use
+      which will set up the correct dependencies. See `nginx::config::site`
+      for an example -- this is a defined type which allows other modules
+      to create an nginx configuration and will make sure it happens after
+      nginx::package and before nginx::service, without the other module
+      even knowing the existence of these classes.
 -   When a class includes or instantiates another class, consider
     whether you need to use the anchor pattern (see below). In
     particular, for a top-level class `foo` which includes