view Versioning.txt @ 0:33c8dd739958

Vendor import of CMF 1.5.2
author fguillaume
date Wed, 20 Jul 2005 16:21:26 +0000
line source
1 Title: Version Control in Zope
2 Description: Content authors and site designers working in complex web
3 sites require support for version control. This chapter introduces
4 versioning in Zope, shows how it can be used, and provides some
5 architectural information about how Zope handles versioning.
6 Subject: products
8 Working on a web site is often a complex activity. There are teams of
9 people with various roles producing content and site design resources.
10 As the site changes over time, it is important to manage the changes.
11 This is the domain of *version control*.
13 This chapter introduces content authors and site designers to the use
14 of versioning in Zope.
16 o Goals of versioning
18 o Quick tour of using the basics in versioning
20 o Advanced operations
22 o Versioning architecture
24 o Glossary of versioning terms
26 Goals
28 There are numerous goals for different audiences that a version
29 control system addresses.
31 xxx fill in some information on goals here.
33 Zope's approach to fulfilling these goals is based on the *DeltaV*
34 model. DeltaV is an extension of the WebDAV protocol, and has
35 recently become achieved "Proposed Standard" status. DeltaV
36 represents the collected wisdom of many professionals in the field
37 of version control systems.
39 While Zope will use the architecture and jargon from DeltaV to
40 accomplish the goals of versioning, there are no current plans to
41 make Zope compliant with the DeltaV protocol. Work on this would be
42 a follow-on project.
44 Quick Start
46 For a quick overview of the basics of version control for content
47 authors, imagine a structured website at a newspaper called Whoville
48 Times (WT), Inc. The WT website is organized similar to the
49 newspaper sections, with extra structure for the web content::
51 /
52 /index.html
53 /logo.gif
54 /styles.css
55 /contacts.html
56 /localnews/
57 /localnews/index.html
58 /localnews/policeblotter.html
59 /sports
60 /sports/index.html
61 /sports/scores.html
62 /livechats/
63 /livechats/index.html
65 There are several people that have access to work on the website,
66 corresponding to editors and writers of the sections of the
67 newspaper. Additionally there are website producers that have
68 privileges in different areas of the site. For instance:
70 o Jane is the senior editor for the website. She can work on any
71 section and approve changes made by others. She is the primary
72 producer for web-only content, such as the Live Chat feature.
74 o Mary is the editor of the Local News section of the newspaper.
75 She also administers this section of the online edition.
77 o Art is the copy editor in the sports department that works on
78 the website.
80 In addition to the site structure, there is another kind of
81 organization that is common in large web productions. That is, the
82 test and production server approach is used to allow material to be
83 authored in one location and deployed in another location. These
84 locations might be on separate machines, in separate Zope processes
85 on the same machine, or in separate folders in the same Zope
86 process. This test/production split is used to allow updates in
87 isolation, thus increasing the quality and stability of the
88 production site.
90 Thus we have an addition to the structure::
92 working/ (Test site)
93 working/index.html
94 working/logo.gif
95 working/styles.css
96 working/contacts.html
97 working/localnews/
98 working/localnews/index.html
99 working/localnews/policeblotter.html
100 working/localnews/headlines.html
101 working/sports
102 working/sports/index.html
103 working/sports/scores.html
104 working/sports/springtraining.html
105 working/livechats/
106 working/livechats/index.html
108 prod/ (Production site)
109 prod/index.html
110 prod/logo.gif
111 prod/styles.css
112 prod/contacts.html
113 prod/localnews/
114 prod/localnews/index.html
115 prod/localnews/policeblotter.html
116 prod/localnews/headlines.html
117 prod/sports
118 prod/sports/index.html
119 prod/sports/scores.html
120 prod/sports/springtraining.html
121 prod/livechats/
122 prod/livechats/index.html
124 In this quickstart section, let's presume that the 'working' and 'prod'
125 sites are already under version control.
127 Making Changes With Versioning
129 Mary begins her website work by updating the police blotter page
130 with new information from the police department. She logs in to
131 the 'working' website, where she authors all her content. Mary
132 then navigates to the police blotter page at
133 '/localnews/policeblotter.html'.
135 Since she is logged in, Mary sees an application bar that isn't
136 visible on the page that the site visitors will see on the
137 production site. The application bar tells her that the police
138 blotter page is checked in and that she is viewing version 1.8 of
139 the page.
141 Mary clicks on 'Edit', makes a change, then clicks on save. The
142 page now says she is viewing version 1.9 of the page. This is
143 because her part of the website is setup to do *autoversioning*.
144 Behind the scenes, every save does a checkout/update/checkin
145 cycle.
147 Mary now wants to update the headlines. This is a page that
148 several of the people in her department edit as soon as something
149 big happens. In the past this has meant that people's changes
150 sometimes overwrite her work. She learned that, to prevent this,
151 she needs to *lock* the page before doing her edits, so that
152 others can neither open the page for editing nor save any changes.
154 Mary visits the 'headlines.html' page which is at version 1.32.
155 This time she clicks on 'Lock and edit'. The application bar
156 indicates that the page is now 'Checked out with lock'. She makes
157 a change and saves the change. She then receives a phone call and
158 makes three more saves during the course of the call. When she is
159 done with the call and her changes, Mary clicks on 'Unlock and
160 checkin' to finish her work on the 'headlines.html' page. She is
161 prompted for a comment to accompany the unlock and checkin
162 operation.
164 The application bar reports that the page is now 'Checked in' and
165 that the version has only increased to 1.33. Why not 1.36? Even
166 though she saved the page 4 times, 'Lock and edit' tells Zope to
167 only do a checkin when the page is unlocked. Thus, in this mode
168 of editing, only one new version is changed for the editing cycle.
170 Art has been working on a major feature about this year's spring
171 training camp for baseball. He has a page at
172 'sports/springtraining.html' where he saves his work and
173 periodically makes it available for review by checking in the
174 page. Art visits the website to makes some changes to the page
175 and to check in the changes.
177 The application bar for the page reports that
178 'springtraining.html' is 'Checked in' and at version 1.5. Art
179 clicks on 'Check out'. The application bar now reports the status
180 of the page as 'Checked out'. Art makes seven edits and realizes
181 he needs some help from a collegue on some wording. The collegue
182 visits the page, and since it isn't locked, makes a quick change.
183 Art then reloads the contents to get the change, makes some more
184 editing, and prepares to finish.
186 Art checks in his changes by clicking on 'Check in'. He is
187 prompted for a comment. He types in a status message and clicks
188 'Done'. The application bar now shows the page as 'Checked in' at
189 version 1.6.
191 Jane is told that the number for the circulation department has
192 changed and she needs to update the site. Since she is an
193 advanced user, Jane uses a desktop editing tool that lets her
194 author content more productively. This editing tool supports the
195 WebDAV protocol.
197 Jane opens her editor, goes to the folder containing the website,
198 and double-clicks on 'contacts.html'. The editor locks the page
199 and opens it for editing. The editor has a property inspector
200 that lets her look at the DAV properties, showing her the current
201 version. Jane makes several changes, saves the document, and
202 closes the document. When the document is closed, the editing
203 tool unlocks the page, prompting Zope to check in a new version.
204 Jane opens the document again and sees that the property sheet
205 says the version has increased.
207 Using Private Workspaces
209 Later in the day, Jane hears that the HTML used by the Local News
210 staff isn't compliant with the HTML 4 specification. She'd like
211 to update all the content, but do so in a way that allows Mary to
212 continue working.
214 To accomplish this, Jane decides to checkout her own version of
215 the content used in the 'localnews' folder. Remember, the folder
216 at '/localnews' and all the content it contains are really
217 checkouts themselves. There is an authoritative copy in the
218 repository, along with all previous versions of the content.
220 Jane uses her web browser to visit the '/localnews' folder. She
221 sees that the folder itself is 'Checked in' and at version 1.3.
222 Jane clicks on 'Copy new checkout'. She then visits her user
223 folder by clicking on 'My Content'. She goes to her 'WORKSPACES'
224 folder and clicks 'Paste'. Zope then does a new checkout of the
225 folder at '/localnews' and the content contained by the folder.
227 Note that, as Jane checks in changes on her own workspace to the
228 local news, the content in '/localnews' doesn't change. Getting
229 Jane's private changes updated in the '/localnews' area requires
230 an explicit step. However, as Mary visits the content in
231 '/localnews', the application bar will indicate that some of the
232 content has been updated in another checkout.
234 xxx What happens if Mary tries to save a change to a version that
235 is no longer the tip?
237 Jane now has her own checkout of the content. Again, Jane is a
238 power user and wants to run a command-line tool that automatically
239 converts all the content to be compliant with the HTML 4 standard.
240 She runs 'sitecopy', a WebDAV tool that downloads all the
241 resources from '~jane/WORKSPACE/localnews' and saves the pages on
242 her local drive. She then runs the 'tidy' command line tool to
243 reformat the HTML. Finally, she runs sitecopy again to upload her
244 changes.
246 Her 'WORKSPACE' area is configured to *not* do autoversioning.
247 Thus, the changes to the resources in '~jane/WORKSPACE/localnews'
248 haven't yet been checked in. Jane uses her web browser to go to
249 the 'localnews' folder in her workspace and verifies that the
250 changes have been uploaded. She then clicks on 'Checkin' to
251 checkin her changes, supplies a comment, then clicks 'Done'.
253 Setting Baselines For Production Content
255 The work for the day is now done and it is time to put out a new
256 edition of the newspaper. In Zope (and DeltaV) jargon, an edition
257 is known as a *baseline*. A baseline is a way to organize the
258 correct version of all the material needed for a website at a
259 certain time. Thus, the live website can run a different baseline
260 than test site. When the test baseline is ready, a new baseline
261 is made from the test site. The production site is then updated
262 to use the new baseline. If something goes wrong, the production
263 site can quickly switch back to the old baseline.
265 The deadline is approaching and everyone has informed Jane that
266 they are finished. Jane goes to the URL at 'working/' and browses
267 the site looking for problems. She notes that the application bar
268 says she is working in 'Baseline: Prod126'.
270 Jane clicks on 'Versioning', then clicks on 'Baseline'. She gets
271 a page that describes all the changes to the site since the last
272 baseline. Everything is in order, so she types 'Prod127' as the
273 label for the new baseline and clicks 'Submit'. The baseline is
274 created and the site is now using the new baseline. Thus, there
275 are no items in the list of changes since the baseline was set.
277 Jane now starts switching the live site to use the new baseline.
278 She goes to the URL at 'prod/' and clicks on 'Version Control',
279 then 'Switch to baseline'. She provides 'Prod127' as the baseline
280 to switch to and clicks 'Done'. After several seconds, the site
281 has all the new and updated content from the test site. Any
282 renames or deletes are also reflected in the production site.
284 Summary
286 This quickstart section provided an overview of how versioning is
287 used in Zope. We showed the various ways that content authors can
288 work on resources using versioning. We also saw how site managers
289 can perform work on the entire body of content.
291 In the remainder of this chapter we will focus on the specifics of
292 each aspect introduced here. We will also look under the covers
293 at the versioning architecture in Zope.
295 Using Version Control
297 Setting Up The Repository
299 - Create new repository, connect to existing repository,
300 disconnect from existing repository
302 Initial Checkout
304 o setting parameters like autoversioning
306 Modes of Authoring
308 - autoversioning on edit, autoversioning on unlock, checkout
310 - viewing changes in context
312 - versioning of configuration content
314 - locking
316 - checked in content can't be edited
318 - working from DAV/ftp
320 o editing and synchronizing
322 o changing the view to show DAV property info
324 - issues for skins and site designers
326 Commit, Update, Discard
328 Working With Version Histories
330 - view versions and change history, compare between versions, copy
331 old version to new version,
333 Workspaces
335 Branches
337 - branching, merging
339 Baselines -- grouping together versions of resources
341 Branching and Merging
343 Reports
345 Configuration and Administration of Versioning
347 - Site policies, collection policies, permissions on version
348 operations,
350 - Administration on repository (e.g. archiving),
352 Architecture
354 o Properties and property sheets as part of versioned resource
356 o DAV properties from DeltaV: which supported?
358 o Different repository implementations (pack, undo, diff, etc.)
360 o Will we have a catalog for fast operations on all versioned
361 content?
363 o Versioned collection issues
365 o Issues involving interactions between versioning and both site
366 catalogs and workflow (e.g. will versioned objects be searchable
367 when they aren't checked in, will two resources that point to the
368 same version both be searchable)
370 o Issues for developers
372 - APIs for versioning, properties for versioning, serialization
374 - preconditions and postconditions on version commits
376 - are properties a logical part of the content being versioned,
377 and does a change to a property generate a new version?
379 Glossary
381 Working server
383 Production server
385 Autoversioning
387 Notes
389 o Is the Site a workspace, baseline, activity, collection, etc.?