[Zope3-checkins] CVS: Zope3/src/zope/fssync - README.txt:1.25
Guido van Rossum
guido@python.org
Mon, 16 Jun 2003 23:17:36 -0400
Update of /cvs-repository/Zope3/src/zope/fssync
In directory cvs.zope.org:/tmp/cvs-serv9854
Modified Files:
README.txt
Log Message:
Added section "Working with bundles." Maybe not quite the right
place, but tbe best I could come up with for now.
=== Zope3/src/zope/fssync/README.txt 1.24 => 1.25 ===
--- Zope3/src/zope/fssync/README.txt:1.24 Wed Jun 4 17:20:35 2003
+++ Zope3/src/zope/fssync/README.txt Mon Jun 16 23:17:35 2003
@@ -13,7 +13,7 @@
http://dev.zope.org/Zope3/ThroughTheWebSiteDevelopment
The "bundles" mentioned there are likely candidates for filesystem
-synchronization.
+synchronization. (See section "Working with bundles" below.)
User stories
@@ -68,7 +68,8 @@
* Another possibility: export and import (a la Zope 2 export/import)
should be easily implemented on top of this. Export would be done
- with checkout; import could be a new "checkin" command.
+ with checkout; import could be a new "checkin" command. (This is
+ now implemented.)
* And last but not least, this will form the basis of bundles; see the
ThroughTheWebSiteDevelopment reference above.
@@ -89,9 +90,6 @@
TO DO
-----
-- Implement checkin, the reverse of checkout (uploading a tree to a
- different Zope instance, where it didn't exist before).
-
- Implement bundle commands.
- On the server side:
@@ -155,3 +153,147 @@
* Commit to multiple Zope instances?
* Diff/merge multiple working sets (a la bitkeeper)?
+
+
+Working with bundles
+--------------------
+
+- Bundles aren't quite as easy to use as they are supposed to be as
+ described in the ThroughTheWebSiteDevelopment Wiki page referenced
+ above, but you can do some basic bundle-ish things. All these need
+ is a little better packaging.
+
+- The fssync command. Below, examples use a command named fssync.
+ This doesn't yet exist. Best is to have a shell alias that points
+ to the file <Zope3>/src/fssync/main.py, where <Zope3> is the root of
+ the Zope3 tree.
+
+- Permissions. Everything described here requires the
+ zope.ManageServices permission, which usually requires being logged
+ in with the manager role.
+
+- Bundle status. There is not yet an explicit notion of "bundle-ness"
+ for site management folders. Any site management folder can be
+ treated as a bundle. Exception: the Bundle view works for the
+ default folder but the form included in the view refuses to change
+ it. This is a safety measure: the bundle form can do a lot of
+ damage, e.g. it can disable all services at once. By convention, I
+ propose that bundles have a folder name of the form
+ <name>-<version>, where <version> is two or more decimal numbers
+ separated by dots and <name> is unconstrained.
+
+- Creating a bundle. There is no specific command to create a
+ bundle. Instead, you create a new site management folder by going
+ to the Contents view of the site (e.g. /++etc++site/@@contents.html)
+ and clicking on "Add" in the actions menu. A box will appear in
+ which you should type the name + version of your bundle. Then in
+ that bundle you should create the things that you want to go into
+ the bundle, e.g. modules, templates, services, utilities, etc.
+
+- Creating a bundle from an existing folder. If you have some
+ existing work done in the default folder or another non-bundle
+ folder, you can save your work to the filesystem using the fssync
+ checkout command, and then check it in under a different name using
+ the fssync checkin command. Example; replace u:p with your manager
+ username and password:
+
+ $ fssync checkout http://u:p@localhost:8080/++etc++site/default
+ <lots of output>
+ All done.
+ $ fssync checkin http://u:p@localhost:8080/++etc++site/bundle-1.0 default
+ $
+
+ Now go back to your web browser and check out the contents of
+ /++etc++site/; a new folder bundle-1.0 should exist, containing a
+ copy of the default folder. You should delete unnecessary things;
+ especially the standard service definitions are not needed.
+
+- Exporting a bundle. First deactivate the bundle bu using the
+ "Deactivate bundle" button on the Bundle tab (see below). Then save
+ the bundle to the filesystem using fssync checkout. Finally tar or
+ zip it up. Make sure to include the @@Zope directory at the same
+ level as the bundle directory in the archive. Example:
+
+ $ fssync checkout http://u:p@localhost:8080/++etc++site/bundle-1.0
+ <lots of output>
+ All done.
+ $ tar tf - bundle-1.0 @@Zope | gzip >bundle-1.0.tgz
+ $
+
+ Now distribute the gzipped tar file file via the web.
+
+- Importing a bundle. First extract the zip or tar file to the
+ filesystem. Then use fssync checkin command to add it to your Zope
+ server. Warning: the checkin command will happily overwrite an
+ existing site management folder!
+
+- Activating a bundle. An imported bundle is completely inactive.
+ Its configuration records (the objects in the bundle's
+ RegistrationManager subfolder, and in RegistrationManager subfolders
+ of subfolders of the bundle) are not registered with their
+ respective services. To activate the bundle, navigate your web
+ browser to its contents and select the Bundle tab; it is probably
+ the second tab from the left. The Bundle tab displays two sections
+ and a few buttons.
+
+ - Section one of the Bundle tab shows the services needed by the
+ bundle. This list is created by inspection of the bundle's
+ configuration records: for example, if there is a configuration
+ record for a utility, the service needs the utility service.
+ For each needed service, there are three possibilities:
+
+ 1) The service is already active in the site. This is probably
+ because it exists in the default folder or in a previous
+ bundle.
+
+ 2) The service is not yet active in the site but the bundle
+ provides a configuration for the service.
+
+ 3) No usable definition of the service can be found. Note that a
+ service active in a parent site cannot be used. This is called
+ an unfulfilled dependency. This means that the bundle cannot
+ be activated. A helpful link to the "Add service" view of the
+ default folder is provided, where you can create (and
+ activate!) the service and then navigate back to the bundle;
+ but you may also import the service as part of another bundle.
+
+ - Section two of the Bundle tab shows, for each of the service types
+ shown in section one, all configuration records in the bundle for
+ that service type. Initially, all configurations are in the
+ "Unregistered" state. At the bottom of the list you will find a
+ button which will register all configurations, and activate the
+ ones that aren't in conflict with pre-existing registrations.
+ Conflicts are indicated in red and provide a link to the
+ conflicting active configuration record, probably in another
+ bundle. The automatic resolution of conflicts in favor of a newer
+ version of the same bundle, mentioned in the Wiki, is not yet
+ implemented; by default, whenever there is a conflict the
+ conflicting configuration record in the bundle is not activated.
+ You can resolve conflicts yourself in favor of the new bundle by
+ clicking the radio button labeled "Register and activate". You
+ can also leave a configuration record inactive by clicking the
+ radio button "Register only". When you are satisfied with the
+ selections, click the "Activate bundle" button below the list to
+ register and activate the bundle's configuration records; this
+ performs the actions selected by the radio buttons. If you later
+ change your mind, you can always go back to the Bundle tab and
+ change your selections.
+
+ - At the very bottom of the page is a button labeled "Deactivate
+ bundle". This is used for uninstalling a bundle; it makes all
+ configuration records contained in the bundle inactive and
+ unregistered. It is also used for exporting a bundle; before you
+ export a bundle, you should deactivate it (see above). In
+ contrast to the description in the Wiki, deactivating a bundle
+ does not reactivate any configuration records that were active
+ before the bundle was activated, because the configuration
+ registries don't record this information; it can't distinguish
+ between previously active and previously registered. A redesign
+ of the registries would be necessary to accommodate this feature.
+
+- To delete a deactivated bundle, go to the site manager's contents
+ display (/++etc++site/@@contents.html), select the checkbox in front
+ of the bundle name, and click the Delete button below the list.
+ Deleting an active bundle usually doesn't work because of the
+ dependencies between the configuration records and the configured
+ objects in the bundle.