ViewVC: Upgrading

#### On this page: Upgrading Basics Upgrading from 0.9 Upgrading from 0.8 | ## Upgrading Basics This document describes some of the things that you will need to consider, change, or handle when upgrading an existing ViewVC or ViewCVS installation to a newer version. Upgrading from an ancient version to the latest version isn't necessarily a multi step process. The instructions are only organized that way. You can certainly upgrade in a single step. It is always recommended to install the new version in a fresh directory and to carefully compare the configuration files. A possible approach is to name the directories `/usr/local/viewvc-1.0`, `/usr/local/viewcvs-1.1` and so on and than create a symbolic link `viewvc` pointing to the production version. This way you can easily test several versions and switch back if your users start to complain. ## Upgrading From ViewCVS 0.9 This section discusses how to upgrade ViewCVS 0.9 to ViewVC 1.0. ### CGI Stubs The CGI stub scripts haved been moved from `<VIEWVC_INSTALLATION_DIRECTORY>/cgi/` to `<VIEWVC_INSTALLATION_DIRECTORY>/bin/cgi/`, so you will need update any ScriptAlias directives pointing to them in your apache configuration. Also, the contents of these scripts have changed, so you may need to replace copies of the old scripts you put in other directories. ### Checkin Database ViewVC 1.0 reads and writes commit times in the MySQL database in UTC time rather than local time. This can cause times displayed on the query page to be a few hours off if an old database is being used with a new version of ViewVC. The best way to fix this is to rebuild the database with the new version of cvsdbadmin, but it is also possible to enable a backwards compatibility mode by setting `utc_time = 0` at the top of lib/dbi.py ### "checkout_magic" Option In ViewVC 1.0, the `checkout_magic` option has been disabled by default to provide a simpler URL scheme that works safely with URL authorization. Most users will not notice any difference in behavior, but users who had been using ViewCVS to browse the contents of static HTML pages stored in a repository may notice that links and images in those pages targetted at other files in the repository no longer display correctly. The new `default_file_view` option can be used to solve this problem and, if neccessary, `checkout_magic` can also be re-enabled. The `viewcvs.conf` file describes these options in detail. ### Configuration Options The following options have been added: general/svn_roots general/root_parents general/use_rcsparse general/cvsnt_exe_path options/template_dir options/docroot options/http_expiration_time options/generate_etags options/root_as_url_component options/default_file_view options/sort_group_dirs options/use_pagesize options/limit_changes options/use_localtime options/cross_copies options/use_highlight options/highlight_path options/highlight_line_numbers options/highlight_convert_tabs options/use_php options/php_path options/svn_path templates/error templates/query_form templates/query_results cvsdb/port cvsdb/rss_row_limit The following options have been removed: general/main_title options/diff_font_face options/diff_font_size options/disable_enscript_lang templates/footer ### Templates The templates have changed drastically in this version of ViewVC. If you are using customized templates from 0.9 or earlier, you will want to port your old customizations to the new template files instead of trying to get the old template files to work with the new ViewVC. There is a new Template Authoring Guide for ViewVC 1.0 templates that can help you with your customizations. And the chart below lists all 0.9 template variables and shows what's become of them in 1.0.
Variable | Location | Changes
--- | --- | ---
ago | markup.ezt | unchanged
author | markup.ezt | unchanged
back_url | log.ezt, log_table.ezt | replaced by `up_href`, which doesn't include the current #file anchor
branch | log.ezt, log_table.ezt | replaced by `default_branch`, which is a list instead of a string
branch | query.ezt | unchanged
branch_names | log.ezt, log_table.ezt | renamed to `branch_tags`
branch_points | markup.ezt | unchanged
branch_tags | dir_alternate.ezt, directory.ezt | unchanged
branches | markup.ezt | unchanged
cfg.general.address | footer.ezt | unchanged
cfg.general.main_title | dir_alternate.ezt, directory.ezt, query.ezt | removed, used to be a string from the configuration file that was shown in the title of the root directory page.
cfg.options.use_cvsgraph | dir_alternate.ezt, directory.ezt | unchanged
cfg.options.use_re_search | dir_alternate.ezt, directory.ezt | unchanged
changed | markup.ezt | unchanged
changes | diff.ezt | attributes changed, see below
changes.extra | diff.ezt | renamed to `changes.line_info_extra`
changes.have_left | diff.ezt | unchanged
changes.have_right | diff.ezt | unchanged
changes.left | diff.ezt | unchanged
changes.line1 | diff.ezt | renamed to `changes.line_info_left`
changes.line2 | diff.ezt | renamed to `changes.line_info_right`
changes.right | diff.ezt | unchanged
changes.type | diff.ezt | new values `binary_diff` and `error`
commits | query.ezt | unchanged
commits.desc | query.ezt | unchanged
commits.files | query.ezt | unchanged
commits.files.author | query.ezt | unchanged
commits.files.branch | query.ezt | unchanged
commits.files.date | query.ezt | unchanged
commits.files.link | query.ezt | unchanged
commits.files.minus | query.ezt | unchanged
commits.files.plus | query.ezt | unchanged
commits.files.rev | query.ezt | unchanged
current_root | dir_alternate.ezt, directory.ezt | renamed to `rootname`
date | query.ezt | unchanged
date1 | diff.ezt | renamed to `date_left`
date2 | diff.ezt | renamed to `date_right`
diff_format | diff.ezt, log.ezt, log_table.ezt | unchanged
directory | query.ezt | unchanged
entries | log.ezt, log_table.ezt | attributes changed, see below
entries.ago | log.ezt, log_table.ezt | unchanged
entries.author | log.ezt, log_table.ezt | unchanged
entries.branch_names | log.ezt | unchanged
entries.branch_point | log.ezt, log_table.ezt | unchanged
entries.branch_points | log.ezt, log_table.ezt | unchanged
entries.branch_points.href | log.ezt, log_table.ezt | unchanged
entries.branch_points.name | log.ezt, log_table.ezt | unchanged
entries.branches | log.ezt, log_table.ezt | unchanged
entries.branches.href | log.ezt, log_table.ezt | unchanged
entries.branches.name | log.ezt, log_table.ezt | unchanged
entries.changed | log.ezt | unchanged
entries.href | log.ezt, log_table.ezt | renamed to `entries.download_href`
entries.html_log | log.ezt, log_table.ezt | renamed to `entries.log`
entries.next_main | log.ezt, log_table.ezt | unchanged
entries.prev | log.ezt, log_table.ezt | unchanged
entries.rev | log.ezt, log_table.ezt | unchanged
entries.state | log.ezt, log_table.ezt | unchanged
entries.tag_names | log.ezt | unchanged
entries.tags | log.ezt, log_table.ezt | unchanged
entries.tags.href | log.ezt | unchanged
entries.tags.name | log.ezt, log_table.ezt | unchanged
entries.text_href | log.ezt, log_table.ezt | renamed to `entries.download_text_href`
entries.to_selected | log.ezt, log_table.ezt | combined into `diff_to_sel_href` variable
entries.utc_date | log.ezt, log_table.ezt | renamed to `entries.date`
entries.vendor_branch | log.ezt, log_table.ezt | unchanged
entries.view_href | log.ezt, log_table.ezt | unchanged
file | query.ezt | unchanged
file_url | header.ezt | renamed to `log_href`
filename | header.ezt | removed, used to be set to the name of the file being shown
files_shown | dir_alternate.ezt, directory.ezt | unchanged
graph_href | log.ezt, log_table.ezt | unchanged
has_tags | dir_alternate.ezt, directory.ezt | removed, used to be a boolean that was true when either tag information was available from the current directory or a tag was set. Determined whether or not to show a tag selector box on the bottom of the directory page.
have_logs | dir_alternate.ezt, directory.ezt | removed, used to be a boolean that was true whenever any logs were being shown in a directory listing. When it was false the template code would omit the log column from the directory table.
head_abs_href | log.ezt, log_table.ezt | renamed to `download_href`
head_href | log.ezt, log_table.ezt | replaced by `view_href` and `download_href`
hidden_values | diff.ezt, log.ezt, log_table.ezt | combined into `*_hidden_values` variables
hide_attic_href | dir_alternate.ezt, directory.ezt | unchanged
hours | query.ezt | unchanged
href | log.ezt, log_table.ezt | combined into `*_href` variables
href | markup.ezt | renamed to `download_href`
human_readable | log.ezt, log_table.ezt | unchanged
imagemap | graph.ezt | unchanged
log | markup.ezt | unchanged
logsort | log.ezt, log_table.ezt | unchanged
mime_type | log.ezt, log_table.ezt, markup.ezt | unchanged
nav_file | markup.ezt | replaced with `nav_path`
nav_path | dir_alternate.ezt, directory.ezt, header.ezt, log.ezt, log_table.ezt | changed from a block of HTML to a list of path components
no_match | dir_alternate.ezt, directory.ezt | removed, used to be a boolean that was true when a directory contained files, but none of them could be displayed due to regular expression or view tag filtering. Would trigger an error message.
num_commits | query.ezt | unchanged
num_files | dir_alternate.ezt, directory.ezt | removed, used to be a count of files in a directory, including dead and filtered files. This number was only shown in the `no_match` error message.
params | dir_alternate.ezt, directory.ezt | replaced by `search_re_hidden_values`
path | header.ezt | removed, used to be set to the directory path of the file being shown
plain_tags | dir_alternate.ezt, directory.ezt | unchanged
prev | markup.ezt | unchanged
qquery | header.ezt | combined into `log_href` variable
qquery | log.ezt, log_table.ezt | replaced by `diff_select_hidden_values`
query | log.ezt, log_table.ezt | combined into `*_href` variables
query | query.ezt | unchanged
repository | query.ezt | unchanged
request.amp_query | graph.ezt | combined into `imagesrc` variable
request.script_name | dir_alternate.ezt, directory.ezt, log.ezt, log_table.ezt | combined into `*_href` variables
request.url | diff.ezt | combined into `diff_format_action` variable
request.url | graph.ezt | combined into `imagesrc` variable
request.where | graph.ezt | renamed to just `where`
rev | graph.ezt | removed, used to be set to the value of the "graph" parameter in CvsGraph page urls. The value was passed on through the `rev` parameter to CvsGraph image URLs, where, oddly enough, it was ignored. It'd be set to a file revision number in directory page graph links, and just "1" in log page graph links.
rev | graph.ezt, header.ezt, markup.ezt | unchanged
rev1 | diff.ezt | renamed to `rev_left`
rev2 | diff.ezt | renamed to `rev_right`
rev_selected | log.ezt, log_table.ezt | unchanged
roots | dir_alternate.ezt, directory.ezt | changed to a list of objects instead of a list of strings
rows | dir_alternate.ezt, directory.ezt | replaced by `entries`
rows.anchor | dir_alternate.ezt, directory.ezt | renamed to `entries.anchor`
rows.author | dir_alternate.ezt, directory.ezt | renamed to `entries.author`
rows.cvs | dir_alternate.ezt, directory.ezt | replaced by `entries.errors`
rows.graph_href | dir_alternate.ezt, directory.ezt | renamed to `entries.graph_href`
rows.href | dir_alternate.ezt, directory.ezt | renamed to `entries.log_href`
rows.log | dir_alternate.ezt, directory.ezt | renamed to `entries.log`
rows.log_file | dir_alternate.ezt, directory.ezt | renamed to `entries.log_file`
rows.log_rev | dir_alternate.ezt, directory.ezt | renamed to `entries.log_rev`
rows.name | dir_alternate.ezt, directory.ezt | renamed to `entries.name`
rows.rev | dir_alternate.ezt, directory.ezt | renamed to `entries.rev`
rows.rev_href | dir_alternate.ezt, directory.ezt | replaced by `entries.view_href` and `entries.download_href`
rows.show_log | dir_alternate.ezt, directory.ezt | removed, used to be a boolean that was true whenever a log message was present for the directory entry.
rows.state | dir_alternate.ezt, directory.ezt | renamed to `entries.state`
rows.time | dir_alternate.ezt, directory.ezt | renamed to `entries.ago`
rows.type | dir_alternate.ezt, directory.ezt | renamed to `entries.pathtype`
search_re | dir_alternate.ezt, directory.ezt | unchanged
selection_form | dir_alternate.ezt, directory.ezt | renamed to `search_re_form`
show_attic_href | dir_alternate.ezt, directory.ezt | unchanged
sortby | dir_alternate.ezt, directory.ezt, query.ezt | unchanged
sortby_author_href | dir_alternate.ezt, directory.ezt | unchanged
sortby_date_href | dir_alternate.ezt, directory.ezt | unchanged
sortby_file_href | dir_alternate.ezt, directory.ezt | unchanged
sortby_log_href | dir_alternate.ezt, directory.ezt | unchanged
sortby_rev_href | dir_alternate.ezt, directory.ezt | unchanged
state | markup.ezt | unchanged
tag | markup.ezt | renamed to `pathrev`
tag1 | diff.ezt | renamed to `tag_left`
tag2 | diff.ezt | renamed to `tag_right`
tags | log.ezt, log_table.ezt | unchanged
tags | markup.ezt | unchanged
tags.name | log.ezt, log_table.ezt | unchanged
tags.rev | log.ezt, log_table.ezt | unchanged
tags | markup.ezt | unchanged
tarball_href | dir_alternate.ezt, directory.ezt | unchanged
text_href | markup.ezt | renamed to `download_text_href`
tr1 | log.ezt, log_table.ezt | removed, used to be a default value for the first text field in the diff selector form. In 1.0, the default value is computed in the templates.
tr2 | log.ezt, log_table.ezt | removed, used to be a default value for the second text field in the diff selector form. In 1.0, the default value is computed in the templates.
unreadable | dir_alternate.ezt, directory.ezt | removed, used to be a boolean that was true whenever any of the files in the directory listing were 'unreadable.' It would trigger a generic error message at the bottom of the page.
utc_date | markup.ezt | renamed to `date`
vendor_branch | markup.ezt | unchanged
view_tag | dir_alternate.ezt, directory.ezt, log.ezt, log_table.ezt | renamed to `pathrev`
viewable | log.ezt, log_table.ezt | renamed to `prefer_markup`
vsn | footer.ezt | unchanged
where | diff.ezt, dir_alternate.ezt, directory.ezt, log.ezt, log_table.ezt | unchanged
who | query.ezt | unchanged
#### Template Arrangement The default templates have been rearranged a bit in ViewVC 1.0. Specifically, "header.ezt" and "footer.ezt" have moved into the "templates/include/" subdirectory. Also, "directory.ezt" and "dir_alternate.ezt" now reference new template files "dir_header.ezt" and "dir_footer.ezt", also found in the "templates/include/" subdirectory. Notably, the "markup.ezt" and "annotate.ezt" templates are now fully self-contained. That is, the markup and annotation data generated by ViewVC is now accessible in those templates just like other template variables. As a result, ViewVC now has no more internal need for the templates.footer configuration variable, so that variable has been removed from the default configuration file. ## Upgrading From ViewCVS 0.8 This section discusses how to upgrade ViewCVS 0.8 to version 0.9 or a later version of the software. NOTE: these changes will bring you up to the requirements of version 0.9. You must also follow the directions for upgrading from 0.9. ### Configuration Options More templates were introduced in version 0.8 of the software, which made many of the configuration options obsolete. This section covers which options were removed. If you made any changes to these options, then you will need to make corresponding changes in the templates. Colors: diff_heading, diff_empty, diff_remove, diff_change, diff_add, and diff_dark_change These options have been incorporated into the `diff.ezt` template. markup_log This option has been incorporated into the `markup.ezt` template. Colors: nav_header and alt_background These options have been incorporated into the `header.ezt` template. Images: back_icon, dir_icon, and file_icon These options have been incorporated into the `directory.ezt`, `header.ezt`, `log.ezt`, `log_table.ezt`, and `query.ezt` templates. use_java_script and open_extern_window The templates now use JavaScript in all applicable places, and open external windows for most downloading and viewing of files. If you wish to not use JavaScript and/or external windows, then remove the feature(s) from the templates. show_author Changing this option would be quite strange and rare. If you do not want to show the author for the revisions, then you should remove it from the various templates. hide_non_readable This option was never used, so it has been removed. flip_links_in_dirview This option is no longer available. If you want the links in your directory view flipped, then you may use the `dir_alternate.ezt` template. ### Template Variables Some template variables that were available in 0.8 have been removed in 0.9. If you have custom templates that refer to these variables, then you will need to modify your templates. `directory.ezt`: headers The headers are now listed explicitly in the template, rather than made available through a list. `directory.ezt`: rows.cols, and rows.span These variables were used in conjunction with the headers variable to control the column displays. This is now controlled explicitly within the templates. `directory.ezt`: rev_in_front This was used to indicate that revision links should be used in the first column, rather than in their standard place in the second column. Changing the links should now be done in the template, rather than according to this variable. You may want to look at the `dir_alternate.ezt` template, which has the revision in front. `directory.ezt`: rows.attic and rows.hide_attic_href These variable were used to manage the hide and showing of the contents of the `Attic/` subdirectory. Several new variables were introduced which can be used to replace this functionality: show_attic_href, hide_attic_href, and rows.state.