store properties in symbol plists

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/guide.rst b/doc/guide.rst
index 200100e..29055f1 100644
--- a/doc/guide.rst
+++ b/doc/guide.rst
@@ -137,3 +137,36 @@ where you can.  Use property combinators.
 When you just want to have a property invoke several others, there are
 functions which you can use to define a new property from the list of old
 ones, which will set all the informational attributes on the host.
+
+Attempting to work with anonymous properties or connection types
+----------------------------------------------------------------
+
+Hosts, property application specifications and deployments are mutable values,
+which you can build, pass around and change in your own code.  For example,
+deployments can be built and executed programmatically.  However, properties
+and connection types should be defined in ``.lisp`` files, loaded into Lisp,
+and then *not* created or modified (except by reloading).  In particular, do
+not try to define properties and connection types programmatically, or try to
+dynamically rebind them.
+
+The reason for this restriction is that some connection types need to invoke
+fresh Lisp processes on remote hosts with (equivalents to) the function
+objects contained in properties and connections available to be called.  Since
+function objects are not serialisable, the only way to do this is to send over
+the contents of your ``.lisp`` files and load the same properties and
+connection types into the remote Lisp.  By contrast, hosts, property
+application specifications and deployments can be serialised and sent over
+that way.
+
+If you were to dynamically rebind properties or connection types in the root
+Lisp, then connections which do not start remote Lisp processes would use your
+new definitions, but connections which start remote Lisp processes would use
+the static definitions in your ``.lisp`` files (or lack definitions
+altogether).  This would violate the idea in Consfigurator that properties,
+including nested deployments, have the same meaning regardless of the
+connection types they are used with.
+
+Note that you *can* programmatically determine what arguments will get passed
+to properties upon deployment, though each of these arguments needs to be
+serialisable, so you can't pass anonymous functions or objects containing
+those.