67
56
directory and to carefully compare the configuration files. A
68
57
possible approach is to name the directories
69
58
<code>/usr/local/viewvc-1.0</code>,
70
<code>/usr/local/viewcvs-1.1</code> and so on and than create a
59
<code>/usr/local/viewvc-1.1</code> and so on and than create a
71
60
symbolic link <code>viewvc</code> pointing to the production
72
61
version. This way you can easily test several versions and switch
73
62
back if your users start to complain.</p>
67
<h2 id="toc">Table of Contents</h2>
69
<li><a href="#introduction">Introduction</a></li>
70
<li><a href="#sec-from-1-0">Upgrading From ViewVC 1.0</a></li>
71
<li><a href="#sec-from-0-9">Upgrading From ViewCVS 0.9</a></li>
72
<li><a href="#sec-from-0-8">Upgrading From ViewCVS 0.8</a></li>
77
<h2 id="sec-from-1-0">Upgrading From ViewVC 1.0</h2>
79
<p>This section discusses how to upgrade ViewVC 1.0.x to ViewVC 1.1.x.</p>
82
<h3>root_as_url_component Now Enabled by Default</h3>
84
<p>In ViewVC 1.1, the <code>root_as_url_component</code> configuration
85
option is now enabled by default. This option causes ViewVC URLs
87
<code>…/root-name/path-in-root[?…]</code> instead of
88
<code>…/path-in-root/?root=root-name[&…]</code>,
89
and makes for a much more intuitive user experience,
90
navigation-wise, when ViewVC is serving up multiple version control
91
repositories. When in this mode, ViewVC will automatically perform
92
the obvious redirection for URLs which have a <code>root=</code>
95
<p>Unfortunately, there's a catch. Older URLs for the default root
96
(specified by the <code>default_root</code> configuration option)
97
were optimized to <em>not</em> include the <code>root=</code> CGI
98
parameter. This means they look unfortunately similar to the newer
99
root-in-the-path URL format, and ViewVC will not attempt to
100
redirect them. But ViewVC won't be able to handle them, either.
101
So, old-style default-root URLs, when aimed at a ViewVC for which
102
the <code>root_as_url_component</code> option has been subsequently
103
enabled, will result in an error. If you need to preserve the
104
functionality of those old URLs, you'll need to either disable
105
<code>root_as_url_component</code>, or use some other mechanism
106
(like server URL rewriting) to morph them into compliance with the
112
<h3>Path-Based Authorization / Forbidden Modules</h3>
114
<p>ViewVC 1.1 introduces a new pluggable authorization (authz)
115
subsystem which gives administrators greater control over the
116
accessibility of the information ViewVC displays in its output.
117
ViewVC provides a number of working authz modules and a framework for
118
configuring them. But of specific interest to folks upgrading from
119
ViewVC 1.0 is that one of these new modules has replaced the
120
handling of forbidden modules. As such, the <code>forbidden</code>
121
configuration option now lives under the configuration section
122
specific to that authz module.</p>
124
<p>Migrating your existing configuration of forbidden modules should
125
be fairly straightforward:</p>
129
<li>In the new "authz-forbidden" section of viewvc.conf, set the
130
<code>forbidden</code> option to the same value as the
131
<code>forbidden</code> option in your ViewVC 1.0.x
132
configuration's "general" section.</li>
134
<li>In the new "authz-forbiddenre" section of viewvc.conf, set the
135
<code>forbiddenre</code> option to the same value as the
136
<code>forbiddenre</code> option in your ViewVC 1.0.x
137
configuration's "general" section.</li>
139
<li>Finally, ensure that that the new <code>authorizer</code>
140
option is set to either "forbidden" or "forbiddenre", depending
141
on which of those you were using in ViewVC 1.0.x.</li>
145
<p>Of course, you might wish to take advantage of another of the
146
provided authz modules. Or, you might wish to write a brand new
147
one for your purposes. The flexibility is yours.</p>
149
<p><strong>Known Issues:</strong></p>
153
<li>ViewVC does not provide an <em>authentication</em> framework.
154
It does, however, inherit authenticated usernames as determined
155
by the HTTP server (Apache, e.g.) via the CGI environment. So,
156
any authorization module that assigns privileges based on
157
usernames will work only if ViewVC is deployed in a way that
158
requires successful authentication (as opposed to allowing
159
anonymous access).</li>
161
<li>Currently, the root listing view only honors the global or
162
vhost-specific configurations, <em>not</em> any root-specific
163
configuration. In the event that ViewVC is using root-specific
164
configuration for its authorization stuffs, this may cause
165
either the unintended leak of root names to users or the
166
inability to see roots at all. However, for root-specific
167
ViewVC views, all configuration — include root-specific
168
configuration — is honored. If you are concerned about
169
leaking root names in the root listing view, you might consider
170
disabling that view altogether by removing <code>roots</code>
171
from the list of views specified in the
172
<code>allowed_views</code> configuration option.</li>
174
<li>The experimental module which allows ViewVC to serve up views
175
of remote Subversion repositories is not yet fully integrated
176
with the authorization subsystem, and almost certainly will
177
leak privileged data. Sorry. That's (one reason) why it's
185
<h3>Syntax Highlighting</h3>
187
<p>ViewVC 1.0.x supports syntax highlighting provided by multiple
188
third-party highlighting engines, including GNU enscript, GNU
189
source-highlight, highlight, php, and py2html. Unfortunately, each
190
of those integrations worked differently than the others. Some
191
supported line numbers, some didn't; some were under active
192
development and recognized newer languages; some weren't; each had
193
its own set of CSS stylations that needed to be customized;
196
<p>In ViewVC 1.1, we've dropped support for all of those integations
197
in favor of a single integration with <a
198
href="http://www.pygments.org/" >Pygments</a>, a
199
Python-module-based syntax highlighting engine. As such, the
200
configuration options for the various other engines (both those
201
that enabled the integration and those that specified the locations
202
of the third-party tools) have been removed from ViewVC, and have
203
been replaced by a single new configuration option:
204
<code>enable_syntax_coloration</code>.</p>
206
<p>The list of removed options is as follows:</p>
209
<li>options/enscript_path</li>
210
<li>options/highlight_convert_tabs</li>
211
<li>options/highlight_path</li>
212
<li>options/markup_line_numbers</li>
213
<li>options/php_exe</li>
214
<li>options/py2html_path</li>
215
<li>options/use_enscript</li>
216
<li>options/use_highlight</li>
217
<li>options/use_pagesize</li>
218
<li>options/use_php</li>
219
<li>options/use_py2html</li>
225
<h3>Checkin Database</h3>
227
<p>ViewVC 1.1 introduces to the <code>cvsdbadmin</code>
228
and <code>svndbadmin</code> tools a new "purge" operation, which
229
allows you to remove all the information related to a given root
230
from your checkins database (without disturbing the information
231
associated with other roots). Likewise, the "rebuild" command in
232
those tools now implies a "purge" followed by an update.</p>
234
<p>As a related change, the <code>svndbadmin</code> program's
235
"rebuild" subcommand has had its purpose become more defined. It
236
no longer accepts a revision argument, and therefore can now only
237
be used to completely rebuild the entirety of the checkin database
238
information for a Subversion repository (instead of being able to
239
only update the information related to single Subversion revision).
240
For per-revision updating, use <code>svndbadmin update</code> and
241
provide a revision (or revision range). And to get the previous
242
rebuild-a-revision effect, pass the new <code>--force</code> option
243
to <code>svndbadmin update</code>.</p>
245
<p>In other words, where you once did this:</p>
247
<blockquote><pre>$ svndbadmin rebuild /path/to/repository 1234
251
<p>you now need to do this:</p>
253
<blockquote><pre>$ svndbadmin update /path/to/repository 1234 --force
257
<p>To enhance the performance of the new "purge" operation, ViewVC 1.1
258
introduces some slight changes to the checkin database schema. If
259
you use the <code>make-database</code> tool to (re)create your
260
checkins database, it will by default employ the new database
261
schema. This should cause the database to be virtually unusable by
262
previous versions of ViewVC, and that's by design. If, however,
263
you need to (re)create your checkins database and you require
264
compatibility with previous versions of ViewVC or ViewCVS, simply
265
pass the "--version=1.0" option to the <code>make-database</code>
266
script. Note that your "purge" and "rebuild" operations could be
267
abysmally slow, though, as that version of the database schema is
268
not optimized for those operations.</p>
273
<h3>Configuration Options</h3>
275
<p>This section covers changes to configuration options not already
276
discussed in other sections pertaining to this upgrade.</p>
278
<p>In ViewVC 1.1, a new "utilities" section was added to the
279
viewvc.conf file. All the options used for configuring the
280
locations of various helper applications that ViewVC uses which
281
were previously scattered throughout the configuration file are now
282
all centralized in this one new section. To accomplish this, the
283
following options were added:</p>
286
<li>utilities/cvsgraph</li>
287
<li>utilities/cvsnt</li>
288
<li>utilities/diff</li>
289
<li>utilities/rcs_dir</li>
290
<li>utilities/svn</li>
293
<p>…and these were removed:</p>
296
<li>general/cvsnt_ext_path</li>
297
<li>general/rcs_path</li>
298
<li>general/svn_path</li>
299
<li>options/cvsgraph_path</li>
302
<p>All the options which governed which ViewVC views were enabled have
303
been consolidated into a single new option. This new option:</p>
306
<li>options/allowed_views</li>
309
<p>…replaces these, which have been removed:</p>
312
<li>options/allow_annotate</li>
313
<li>options/allow_markup</li>
314
<li>options/allow_tar</li>
317
<p>ViewVC now honors the "svn:mime-type" property stored on
318
Subversion-versioned files as the primary source of MIME type
319
determination (before falling back to name-based MIME mappings and
320
such). However, this can negatively affect the viewability of
321
certain files — especially images — whose
322
"svn:mime-type" properties are set incorrectly, such as will happen
323
if Subversion itself merely determines that the file isn't
324
human-readable and uses the "application/octet-stream" MIME type to
325
record this determination. To make ViewVC <em>not</em> honor the
326
"svn:mime-type" property value, set the <code>svn_ignore_mimetype</code>
327
configuration option.</p>
329
<p>Speaking of MIME types, the option <code>mime_types_file</code> is
330
now <code>mime_types_files</code>, as it now carries multiple paths
331
to MIME mappings files, ordered by preference.</p>
333
<p>The <code>use_rcsparse</code> option was moved from the "general"
334
section to the "options" section.</p>
336
<p>The <code>log_sort</code> option's value "cvs" has been renamed to
337
"none" (for general application across all supported version
338
control systems).</p>
340
<p>Custom sections which define per-virtual-host configuration option
341
overrides must now have their names prefixed with "vhost-". Also,
342
instead of a hyphen (-) between the virtual host name and the base
343
configuration section being overridden, now there should be a
344
forward slash character (/). For example, the following
345
configuration which was valid in ViewVC 1.0 is no longer valid:</p>
347
<blockquote><pre>[vhosts]
351
allowed_views = annotate, diff, markup, tar
355
<p>This now needs to be written like so:</p>
357
<blockquote><pre>[vhosts]
361
allowed_views = annotate, diff, markup, tar
365
<p>The following is a grab-bag of additional new options:</p>
368
<li>options/hide_errorful_entries</li>
369
<li>options/mangle_email_addresses</li>
377
<p>This section describes template variable changes introduced in this
378
release. See the <a href="./template-authoring-guide.html">Template
379
Authoring Guide</a> for the current set of variables available to
382
<p>One notable change in ViewVC 1.1 is that the markup.ezt and
383
annotate.ezt templates have been combined into a single file.ezt
386
<p>Also, the configuration options under the <code>[templates]</code>
387
section are now paths relative to the configured template directory
388
(either the value of the <code>options/template_dir</code>
389
option, or the default "templates" directory), instead of being
390
relative to the configuration location.</p>
402
<td class="varname">rootpath</td>
403
<td><em>all templates</em></td>
407
<td class="varname">change_root_action</td>
408
<td><em>all templates</em></td>
412
<td class="varname">change_root_hidden_values</td>
413
<td><em>all templates</em></td>
417
<td class="varname">roots</td>
418
<td><em>all templates</em> except roots.ezt</td>
422
<td class="varname">roots.path</td>
427
<td class="varname">queryform_href</td>
428
<td>diff.ezt, file.ezt, graph.ezt, log.ezt, log_table.ezt,
429
query_form.ezt, revision.ezt, roots.ezt</td>
433
<td class="varname">tarball_href</td>
434
<td>diff.ezt, file.ezt, graph.ezt, log.ezt, log_table.ezt,
435
query_form.ezt, query_results.ezt, revision.ezt, roots.ezt</td>
439
<td class="varname">properties</td>
440
<td>directory.ezt, file.ezt</td>
444
<td class="varname">properties.name</td>
445
<td>directory.ezt, file.ezt</td>
449
<td class="varname">properties.undisplayable</td>
450
<td>directory.ezt, file.ezt</td>
454
<td class="varname">properties.value</td>
455
<td>directory.ezt, file.ezt</td>
459
<td class="varname">diff_format_hidden_values</td>
461
<td>now is an iterable list of objects with .name and .value attributes</td>
464
<td class="varname">diff_type</td>
466
<td>new value: <code>f</code></td>
469
<td class="varname">date_left</td>
471
<td>renamed to <code>left.date</code></td>
474
<td class="varname">path_left</td>
476
<td>renamed to <code>left.path</code></td>
479
<td class="varname">rev_left</td>
481
<td>renamed to <code>left.rev</code></td>
484
<td class="varname">tag_left</td>
486
<td>renamed to <code>left.tag</code></td>
489
<td class="varname">date_right</td>
491
<td>renamed to <code>right.date</code></td>
494
<td class="varname">path_right</td>
496
<td>renamed to <code>right.path</code></td>
499
<td class="varname">rev_right</td>
501
<td>renamed to <code>right.rev</code></td>
504
<td class="varname">tag_right</td>
506
<td>renamed to <code>right.tag</code></td>
509
<td class="varname">annotate_href</td>
511
<td>removed, use <code>right.annotate_href</code> instead</td>
514
<td class="varname">left.annotate_href</td>
519
<td class="varname">left.download_href</td>
524
<td class="varname">left.download_text_href</td>
529
<td class="varname">left.prefer_markup</td>
534
<td class="varname">left.revision_href</td>
539
<td class="varname">left.view_href</td>
544
<td class="varname">right.annotate_href</td>
549
<td class="varname">right.download_href</td>
554
<td class="varname">right.download_text_href</td>
559
<td class="varname">right.prefer_markup</td>
564
<td class="varname">right.revision_href</td>
569
<td class="varname">right.view_href</td>
574
<td class="varname">right.view_href</td>
579
<td class="varname">dir_paging_hidden_values</td>
580
<td>directory.ezt, , dir_alternate.ezt</td>
581
<td>now is an iterable list of objects with .name and .value attributes</td>
584
<td class="varname">entries.log</td>
585
<td>directory.ezt, dir_alternate.ezt</td>
586
<td>now always contains untruncated log message</td>
589
<td class="varname">entries.short_log</td>
590
<td>directory.ezt, dir_alternate.ezt</td>
594
<td class="varname">search_re_hidden_values</td>
595
<td>directory.ezt, dir_alternate.ezt</td>
596
<td>now is an iterable list of objects with .name and .value attributes</td>
599
<td class="varname">search_tag_hidden_values</td>
600
<td>directory.ezt, dir_alternate.ezt</td>
601
<td>now is an iterable list of objects with .name and .value attributes</td>
604
<td class="varname">pathrev_clear_hidden_values</td>
605
<td>log.ezt, log_table.ezt, directory.ezt, dir_alternate.ezt</td>
606
<td>now is an iterable list of objects with .name and .value attributes</td>
609
<td class="varname">pathrev_hidden_values</td>
610
<td>log.ezt, log_table.ezt, directory.ezt, dir_alternate.ezt</td>
611
<td>now is an iterable list of objects with .name and .value attributes</td>
614
<td class="varname">annotate_href</td>
615
<td>log.ezt, log_table.ezt</td>
616
<td>renamed to <code>head_annotate_href</code></td>
619
<td class="varname">diff_form_hidden_values</td>
620
<td>log.ezt, log_table.ezt</td>
621
<td>now is an iterable list of objects with .name and .value attributes</td>
624
<td class="varname">download_href</td>
625
<td>log.ezt, log_table.ezt</td>
626
<td>renamed to <code>head_download_href</code></td>
629
<td class="varname">download_text_href</td>
630
<td>log.ezt, log_table.ezt</td>
631
<td>renamed to <code>head_download_text_href</code></td>
634
<td class="varname">log_paging_hidden_values</td>
635
<td>log.ezt, log_table.ezt</td>
636
<td>now is an iterable list of objects with .name and .value attributes</td>
639
<td class="varname">logsort_hidden_values</td>
640
<td>log.ezt, log_table.ezt</td>
641
<td>now is an iterable list of objects with .name and .value attributes</td>
644
<td class="varname">prefer_markup</td>
645
<td>log.ezt, log_table.ezt</td>
646
<td>renamed to <code>head_prefer_markup</code></td>
649
<td class="varname">view_href</td>
650
<td>log.ezt, log_table.ezt</td>
651
<td>renamed to <code>head_view_href</code></td>
654
<td class="varname">rss_link_href</td>
655
<td>query.ezt, rss.ezt</td>
659
<td class="varname">query_hidden_values</td>
660
<td>query_form.ezt</td>
661
<td>now is an iterable list of objects with .name and .value attributes</td>
664
<td class="varname">jump_rev_hidden_values</td>
665
<td>revision.ezt</td>
666
<td>now is an iterable list of objects with .name and .value attributes</td>
669
<td class="varname">num_changes</td>
670
<td>revision.ezt</td>
78
680
<h2 id="sec-from-0-9">Upgrading From ViewCVS 0.9</h2>
80
682
<p>This section discusses how to upgrade ViewCVS 0.9 to ViewVC 1.0.</p>
82
685
<h3>CGI Stubs</h3>
84
687
<p>The CGI stub scripts haved been moved from
added
removed
docs/upgrading-howto.html
