[CMF-checkins] SVN: CMF/trunk/docs/Versioning.txt - remove decoy
Jens Vagelpohl
jens at dataflake.org
Sun Jan 15 06:05:33 EST 2006
Log message for revision 41316:
- remove decoy
Changed:
D CMF/trunk/docs/Versioning.txt
-=-
Deleted: CMF/trunk/docs/Versioning.txt
===================================================================
--- CMF/trunk/docs/Versioning.txt 2006-01-15 10:57:10 UTC (rev 41315)
+++ CMF/trunk/docs/Versioning.txt 2006-01-15 11:05:32 UTC (rev 41316)
@@ -1,389 +0,0 @@
-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.?
More information about the CMF-checkins
mailing list