[CMF-checkins] CVS: CMF/docs - Versioning.txt:1.1 Outline.stx:1.2

[Paul Everitt]

Update of /cvs-repository/CMF/docs
In directory cvs.zope.org:/tmp/cvs-serv10153

Modified Files:
	Outline.stx 
Added Files:
	Versioning.txt 
Log Message:
Updated TOC, added versioning notes

=== Added File CMF/docs/Versioning.txt ===
Title: Version Control in Zope
Description: Content authors and site designers working in complex web
sites require support for version control.  This chapter introduces
versioning in Zope, shows how it can be used, and provides some
architectural information about how Zope handles versioning.
Subject: products

Working on a web site is often a complex activity.  There are teams of
people with various roles producing content and site design resources.
As the site changes over time, it is important to manage the changes.
This is the domain of *version control*.

This chapter introduces content authors and site designers to the use
of versioning in Zope.

   o Goals of versioning

   o Quick tour of using the basics in versioning

   o Advanced operations

   o Versioning architecture

   o Glossary of versioning terms

Goals

  There are numerous goals for different audiences that a version
  control system addresses.  

  xxx fill in some information on goals here.

  Zope's approach to fulfilling these goals is based on the *DeltaV*
  model.  DeltaV is an extension of the WebDAV protocol, and has
  recently become achieved "Proposed Standard" status.  DeltaV
  represents the collected wisdom of many professionals in the field
  of version control systems.

  While Zope will use the architecture and jargon from DeltaV to
  accomplish the goals of versioning, there are no current plans to
  make Zope compliant with the DeltaV protocol.  Work on this would be
  a follow-on project.

Quick Start

  For a quick overview of the basics of version control for content
  authors, imagine a structured website at a newspaper called Whoville
  Times (WT), Inc.  The WT website is organized similar to the
  newspaper sections, with extra structure for the web content::

    /
      /index.html
      /logo.gif
      /styles.css
      /contacts.html
      /localnews/
        /localnews/index.html
	/localnews/policeblotter.html
      /sports
        /sports/index.html
	/sports/scores.html
      /livechats/
        /livechats/index.html

  There are several people that have access to work on the website,
  corresponding to editors and writers of the sections of the
  newspaper.  Additionally there are website producers that have
  privileges in different areas of the site.  For instance:

    o Jane is the senior editor for the website.  She can work on any
    section and approve changes made by others.  She is the primary
    producer for web-only content, such as the Live Chat feature.

    o Mary is the editor of the Local News section of the newspaper.
    She also administers this section of the online edition.

    o Art is the copy editor in the sports department that works on
    the website.

  In addition to the site structure, there is another kind of
  organization that is common in large web productions.  That is, the
  test and production server approach is used to allow material to be
  authored in one location and deployed in another location.  These
  locations might be on separate machines, in separate Zope processes
  on the same machine, or in separate folders in the same Zope
  process.  This test/production split is used to allow updates in
  isolation, thus increasing the quality and stability of the
  production site.

  Thus we have an addition to the structure::

    working/   (Test site)
      working/index.html
      working/logo.gif
      working/styles.css
      working/contacts.html
      working/localnews/
        working/localnews/index.html
	working/localnews/policeblotter.html
	working/localnews/headlines.html
      working/sports
        working/sports/index.html
	working/sports/scores.html
	working/sports/springtraining.html
      working/livechats/
        working/livechats/index.html

    prod/  (Production site)
      prod/index.html
      prod/logo.gif
      prod/styles.css
      prod/contacts.html
      prod/localnews/
        prod/localnews/index.html
	prod/localnews/policeblotter.html
	prod/localnews/headlines.html
      prod/sports
        prod/sports/index.html
	prod/sports/scores.html
	prod/sports/springtraining.html
      prod/livechats/
        prod/livechats/index.html

  In this quickstart section, let's presume that the 'working' and 'prod'
  sites are already under version control.

  Making Changes With Versioning

    Mary begins her website work by updating the police blotter page
    with new information from the police department.  She logs in to
    the 'working' website, where she authors all her content.  Mary
    then navigates to the police blotter page at
    '/localnews/policeblotter.html'.

    Since she is logged in, Mary sees an application bar that isn't
    visible on the page that the site visitors will see on the
    production site.  The application bar tells her that the police
    blotter page is checked in and that she is viewing version 1.8 of
    the page.

    Mary clicks on 'Edit', makes a change, then clicks on save.  The
    page now says she is viewing version 1.9 of the page.  This is
    because her part of the website is setup to do *autoversioning*.
    Behind the scenes, every save does a checkout/update/checkin
    cycle.

    Mary now wants to update the headlines.  This is a page that
    several of the people in her department edit as soon as something
    big happens.  In the past this has meant that people's changes
    sometimes overwrite her work.  She learned that, to prevent this,
    she needs to *lock* the page before doing her edits, so that
    others can neither open the page for editing nor save any changes.

    Mary visits the 'headlines.html' page which is at version 1.32.
    This time she clicks on 'Lock and edit'.  The application bar
    indicates that the page is now 'Checked out with lock'.  She makes
    a change and saves the change.  She then receives a phone call and
    makes three more saves during the course of the call.  When she is
    done with the call and her changes, Mary clicks on 'Unlock and
    checkin' to finish her work on the 'headlines.html' page.  She is
    prompted for a comment to accompany the unlock and checkin
    operation.

    The application bar reports that the page is now 'Checked in' and
    that the version has only increased to 1.33.  Why not 1.36?  Even
    though she saved the page 4 times, 'Lock and edit' tells Zope to
    only do a checkin when the page is unlocked.  Thus, in this mode
    of editing, only one new version is changed for the editing cycle.

    Art has been working on a major feature about this year's spring
    training camp for baseball.  He has a page at
    'sports/springtraining.html' where he saves his work and
    periodically makes it available for review by checking in the
    page.  Art visits the website to makes some changes to the page
    and to check in the changes.

    The application bar for the page reports that
    'springtraining.html' is 'Checked in' and at version 1.5.  Art
    clicks on 'Check out'.  The application bar now reports the status
    of the page as 'Checked out'.  Art makes seven edits and realizes
    he needs some help from a collegue on some wording.  The collegue
    visits the page, and since it isn't locked, makes a quick change.
    Art then reloads the contents to get the change, makes some more
    editing, and prepares to finish.

    Art checks in his changes by clicking on 'Check in'.  He is
    prompted for a comment.  He types in a status message and clicks
    'Done'.  The application bar now shows the page as 'Checked in' at
    version 1.6.

    Jane is told that the number for the circulation department has
    changed and she needs to update the site.  Since she is an
    advanced user, Jane uses a desktop editing tool that lets her
    author content more productively.  This editing tool supports the
    WebDAV protocol.

    Jane opens her editor, goes to the folder containing the website,
    and double-clicks on 'contacts.html'.  The editor locks the page
    and opens it for editing.  The editor has a property inspector
    that lets her look at the DAV properties, showing her the current
    version.  Jane makes several changes, saves the document, and
    closes the document.  When the document is closed, the editing
    tool unlocks the page, prompting Zope to check in a new version.
    Jane opens the document again and sees that the property sheet
    says the version has increased.

  Using Private Workspaces

    Later in the day, Jane hears that the HTML used by the Local News
    staff isn't compliant with the HTML 4 specification.  She'd like
    to update all the content, but do so in a way that allows Mary to
    continue working.

    To accomplish this, Jane decides to checkout her own version of
    the content used in the 'localnews' folder.  Remember, the folder
    at '/localnews' and all the content it contains are really
    checkouts themselves.  There is an authoritative copy in the
    repository, along with all previous versions of the content.

    Jane uses her web browser to visit the '/localnews' folder.  She
    sees that the folder itself is 'Checked in' and at version 1.3.
    Jane clicks on 'Copy new checkout'.  She then visits her user
    folder by clicking on 'My Content'.  She goes to her 'WORKSPACES'
    folder and clicks 'Paste'.  Zope then does a new checkout of the
    folder at '/localnews' and the content contained by the folder.

    Note that, as Jane checks in changes on her own workspace to the
    local news, the content in '/localnews' doesn't change.  Getting
    Jane's private changes updated in the '/localnews' area requires
    an explicit step.  However, as Mary visits the content in
    '/localnews', the application bar will indicate that some of the
    content has been updated in another checkout.

    xxx What happens if Mary tries to save a change to a version that
    is no longer the tip?

    Jane now has her own checkout of the content.  Again, Jane is a
    power user and wants to run a command-line tool that automatically
    converts all the content to be compliant with the HTML 4 standard.
    She runs 'sitecopy', a WebDAV tool that downloads all the
    resources from '~jane/WORKSPACE/localnews' and saves the pages on
    her local drive.  She then runs the 'tidy' command line tool to
    reformat the HTML.  Finally, she runs sitecopy again to upload her
    changes.

    Her 'WORKSPACE' area is configured to *not* do autoversioning.
    Thus, the changes to the resources in '~jane/WORKSPACE/localnews'
    haven't yet been checked in.  Jane uses her web browser to go to
    the 'localnews' folder in her workspace and verifies that the
    changes have been uploaded.  She then clicks on 'Checkin' to
    checkin her changes, supplies a comment, then clicks 'Done'.

  Setting Baselines For Production Content

    The work for the day is now done and it is time to put out a new
    edition of the newspaper.  In Zope (and DeltaV) jargon, an edition
    is known as a *baseline*.  A baseline is a way to organize the
    correct version of all the material needed for a website at a
    certain time.  Thus, the live website can run a different baseline
    than test site.  When the test baseline is ready, a new baseline
    is made from the test site.  The production site is then updated
    to use the new baseline.  If something goes wrong, the production
    site can quickly switch back to the old baseline.

    The deadline is approaching and everyone has informed Jane that
    they are finished.  Jane goes to the URL at 'working/' and browses
    the site looking for problems.  She notes that the application bar
    says she is working in 'Baseline: Prod126'.

    Jane clicks on 'Versioning', then clicks on 'Baseline'.  She gets
    a page that describes all the changes to the site since the last
    baseline.  Everything is in order, so she types 'Prod127' as the
    label for the new baseline and clicks 'Submit'.  The baseline is
    created and the site is now using the new baseline.  Thus, there
    are no items in the list of changes since the baseline was set.

    Jane now starts switching the live site to use the new baseline.
    She goes to the URL at 'prod/' and clicks on 'Version Control',
    then 'Switch to baseline'.  She provides 'Prod127' as the baseline
    to switch to and clicks 'Done'.  After several seconds, the site
    has all the new and updated content from the test site.  Any
    renames or deletes are also reflected in the production site.

  Summary

    This quickstart section provided an overview of how versioning is
    used in Zope.  We showed the various ways that content authors can
    work on resources using versioning.  We also saw how site managers
    can perform work on the entire body of content.

    In the remainder of this chapter we will focus on the specifics of
    each aspect introduced here.  We will also look under the covers
    at the versioning architecture in Zope.

Using Version Control

  Setting Up The Repository

    - Create new repository, connect to existing repository,
    disconnect from existing repository

  Initial Checkout

    o setting parameters like autoversioning

  Modes of Authoring

    - autoversioning on edit, autoversioning on unlock, checkout

    - viewing changes in context

    - versioning of configuration content

    - locking

    - checked in content can't be edited

    - working from DAV/ftp

      o editing and synchronizing

      o changing the view to show DAV property info

    - issues for skins and site designers

  Commit, Update, Discard

  Working With Version Histories

    - view versions and change history, compare between versions, copy
    old version to new version,

  Workspaces

  Branches

    - branching, merging

  Baselines -- grouping together versions of resources

  Branching and Merging

  Reports

  Configuration and Administration of Versioning

    - Site policies, collection policies, permissions on version
    operations,

    - Administration on repository (e.g. archiving), 

Architecture

  o Properties and property sheets as part of versioned resource

  o DAV properties from DeltaV: which supported?

  o Different repository implementations (pack, undo, diff, etc.)

  o Will we have a catalog for fast operations on all versioned
  content?

  o Versioned collection issues

  o Issues involving interactions between versioning and both site
  catalogs and workflow (e.g. will versioned objects be searchable
  when they aren't checked in, will two resources that point to the
  same version both be searchable)

  o Issues for developers

    - APIs for versioning, properties for versioning, serialization

    - preconditions and postconditions on version commits

    - are properties a logical part of the content being versioned,
    and does a change to a property generate a new version?

Glossary

  Working server

  Production server

  Autoversioning

Notes

  o Is the Site a workspace, baseline, activity, collection, etc.?


=== CMF/docs/Outline.stx 1.1 => 1.2 ===
 
+  Introduction
+
+    - What is content management, what is unique about CMF, what's the
+      future for the CMF
+
   Quickstart
 
     Installing 
 
   Overview of Content Types
 
+    - Site, Folder, Topic, Document, Image, etc.
+
+    - Remote authoring
+
+    - Formats (stx, html)
+
   CMF Services
 
+    - Skins, workflow, cataloging, syndication, discussion,
+      membership, versioning, personalization, authentication sources,
+
   CMF Configuration
 
+    - security settings, default skins, reconfigure portal options,
+      editing selection of subjects, discussability, DAV, cookie
+      crumbler, virtual host monster, reviewers
+
   Customizing Look and Feel
 
   CMF Interfaces
 
+  Glossary
+
+  Notes
+
+    - Emphasize the *demo* aspect of demo folder
+
+    - Emphasize fundamental ideas: content types, services, skins