[Checkins] SVN: zc.recipe.zope3instance/branches/gocept-zconf-slug-dev/src/zc/recipe/zope3instance/experiments.txt - clarified our goals and approach a bit more

[Christian Theune]

Log message for revision 71468:
   - clarified our goals and approach a bit more
  

Changed:
  U   zc.recipe.zope3instance/branches/gocept-zconf-slug-dev/src/zc/recipe/zope3instance/experiments.txt

-=-
Modified: zc.recipe.zope3instance/branches/gocept-zconf-slug-dev/src/zc/recipe/zope3instance/experiments.txt
===================================================================
--- zc.recipe.zope3instance/branches/gocept-zconf-slug-dev/src/zc/recipe/zope3instance/experiments.txt	2006-12-06 20:41:21 UTC (rev 71467)
+++ zc.recipe.zope3instance/branches/gocept-zconf-slug-dev/src/zc/recipe/zope3instance/experiments.txt	2006-12-06 20:57:56 UTC (rev 71468)
@@ -9,38 +9,74 @@
 This document describes the experiments and changes that we started to
 introduce in our branch of the zope3instance recipe.
 
-Generic skeleton
-================
 
-We wanted all configuration files to be customizable for each instance part.
-We need to change the existing ZCML and zope.conf files in ways that were
-unanticipated by the recipe up until now and are probably out of the scope of
-configuration via buildout.
+An instance's parts directory
+=============================
 
-Many changes are inherent for a certain part, especially as the zope3instance
-recipe represents a software installation that has a certain policy, described
-by ZCML.
+The minimal files that are expected in an instance directory are:
 
-We started looking at Zope 3 instances as the incarnation of a certain
-application instead of a generic server container where software can later be
-installed at a user's will. 
+  - zdaemon.conf
+  - zope.conf
+  - ftesting.zcml
+  - site.zcml (just a policy, depends on zope.conf)
 
-This led to a grey area where policies are determined. Zope 3 intends this to
-be the scope of ZCML. 
 
-Therefore we changed the instance recipe to use a skeleton directory, found
-via <buildout-path>/skels/<partname>.
+Using skeletons and configuration options
+=========================================
 
-All files from this directory are copied into the instance part.
+Our goal is to allow customization of all configuration files for each part.
 
+However, we have several projects where the *simplest* way to specify how we
+want an instance to be configured is to manually provide a variation of either
+site.zcml or zope.conf.
 
-Simple configuration options
-============================
+Those changes in site.zcml or zope.conf are a mostly inherent part 
+of how our applications work and what they need and do not change for
+individual installations.
 
+However, there are typical changes that need to be applied on a per-buildout
+basis, like setting correct IP addresses, configuring databases etc.
+
+To allow both use cases we envision a skeleton approach to be useful:
+
+- Provide an overlaying approach to copy the required files into the 
+  parts' directory with global defaults and local customizations on a 
+  per-file basis.
+
+- Use simple string interpolation for files that end with '.in' to fill in 
+  options from buildout.cfg and rename the '.in' files.
+
+
+Skeleton overlays
+-----------------
+
+This recipe pays attention to two sources for skeleton files:
+
+- the global skeleton directory as provided by this recipe
+- the local skeleton directory for each part
+
+The global skeleton directory is fixed and provided with this recipe. This has
+a drawback though: the zope.conf and site.zcml files depend on varying degrees
+on the zope version that is used. Unfortunately we use a different (much
+simpler) layout for our ZCML than the normal Zope 3 skeleton does, also we use
+a different syntax than the normal Zope 3 skeleton mechanism.
+
+The local skeleton directory is optional for each part. This recipe uses
+the directory <buildout>/skels/<partname> if it exists as the local skeleton
+directory.
+
+The two skeleton directories work together in the sense that the global
+skeleton directory is copied first, then the local directory. Therefor local
+customizations can overwrite the global defaults.
+
+Configuration options from buildout.cfg
+---------------------------------------
+
 After copying the skeleton files, the parts directory for the instance is
 scanned for any files whose names end with ".in".
 
-For those, the content is read and a string interpolation is applied using the
-configuration section of that part from the buildout config. After the
-interpolation, the data is written to the file, the trailing '.in' removed
-from the filename.
+For those files, the content is read and a string interpolation is applied
+using the configuration section from the instance part.
+
+Finally, the new configuration file is written (without '.in') and the '.in'
+file is removed.