ViewVC: Upgrading

# Upgrading ViewVC

## Table of Contents

## Introduction

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/viewvc-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.

Please note that every ViewVC release—even patch releases—may deliver a new feature, a new configuration option, a new template data dictionary item. But we try to avoid introducing changes that would cause an existing ViewVC installation to stop functioning, or to function wildly different, in mere patch releases. That's why this document offers guidance for upgrades only across major and minor release lines of ViewVC. For patch release upgrades, your best bet is to carefully examine the distributed configuration file templates (`viewvc.conf.dist`, etc.).

## Upgrading From ViewVC 1.3

This section discusses how to upgrade ViewVC 1.3.x to ViewVC 1.4.x.

### ...

## Upgrading From ViewVC 1.2

This section discusses how to upgrade ViewVC 1.2.x to ViewVC 1.3.x.

### Minimum Python Version Changed

ViewVC 1.3 requires Python 3, with a minimum version of Python 3.10.

Bringing Python 3 support to ViewVC was, in fact, the single motivating feature of the release. The migration of the codebase to Python 3 necessitated a relatively major overhaul to the way that strings were handled within the codebase, especially those strings which carry non-ASCII characters (versioned file names, commit metadata, system paths, etc.). As such, see below for a number of new configuration options that ViewVC administrators may wish to consider as they migrate to ViewVC 1.3.

### Commits Database

The commits database feature now requires MySQL 5.7+ or MariaDB 10.2+; Support for older versions have been discontinued. Additionally, a new schema has been introduced for the feature that specifically declares that text fields use UTF-8 character encoding. ViewVC 1.3.x will yield an error when asked to interact with existing databases that use older schemas. Administrators who are using the commits database feature today should drop and completely rebuild their database from scratch (after making a backup, of course). No schema migration has been developed to shortcut this process.

NOTE: We recommend this even for those who were "early adopters" of the unreleased 1.3.x-dev codebase. While ViewVC 1.3.0 may continue to work with those databases, we cannot guarantee as much.

Fortunately, ViewVC's database-related tooling remains largely unchanged from prior versions, with one notable exception: make-database now requires the --force option to be provided when asked to create a new database atop one that already exists. But repository hook script integrations should not require additional configuration.

### New CGI Script for IIS

The `bin/cgi/viewvc.cgi` script no longer supports IIS deployments unless those have been specifically configured to populate the PATH_INFO CGI variable in a manner more compliant with the CGI specification. Such configuration is done different depending on the version of IIS — via the AllowPathInfo option for IIS 7.0 or newer; via the AllowPathInfoForScriptMappings metabase property for older versions. For IIS servers which continue to use the default handling of PATH_INFO, though, ViewVC 1.3 provides a new `bin/cgi/iis/viewvc.cgi` script.

To summarize, administrators deploying ViewVC as a CGI script under IIS have two options:

- If the appropriate PATH_INFO population setting (mentioned above) has not been modified from its default value, use the new `bin/cgi/iis/viewvc.cgi` script.
- Otherwise, continue to use `bin/cgi/viewvc.cgi`.

### Binary File Handling

The options/binary_mime_types option has changed slightly in that glob patterns (such as "image/*") no longer apply to the three "web-friendly" image formats. Administrators who wish to forbid viewing these images types ("image/gif", "image/jpeg", and "image/png") should add them explicitly to this option's value (in addition, if you wish, to a blanket "image/*" pattern that covers all other image types). Of course, if your installation does not allow the use of the "co" ("checkout" or "download") view, embedded web-friendly images will not be displayed even if not explicitly forbidden by this option.

Additionally, what ViewVC does with binary files has changed. Rather than raising a page-level exception on a request to view a binary file's content or diff, ViewVC will avoid showing the deemed-to-be-unreadable file content but still preserve its own page layout and navigation.

Finally, recognizing the challenges of handling even human-readable file content (which as of this release implies an ability to perfectly represent that content as Unicode), we've added a new options/allow_mojibake option that administrators can enable in order to force ViewVC to fall back to a lossy Unicode transformation and present those results to the user. This is rougly analogous to the old hide_binary_garbage template-defined flag that was present in some previous ViewVC template sets. Note that this option does not override other determinations of "binariness" (such as the application of options/binary_mime_types).

### Configuration Options

This section covers changes to configuration options not already discussed in other sections pertaining to this upgrade.

The following new configuration options were introduced (the documentation for which can be found alongside the option's default value in the viewvc.conf.dist file):

- options/default_encoding
- options/root_path_locale
- utilities/max_context

The following configuration options were removed:

- options/checkout_magic

## Upgrading From ViewVC 1.1

This section discusses how to upgrade ViewVC 1.1.x to ViewVC 1.2.x.

### Minimum Python Version Changed

ViewVC 1.2 requires Python 2, with a minimum version of Python 2.4. Sorry, there's no Python 3 support yet.

As of January 1, 2020, Python 2 is essentially unsupported (and Python 1 support has long, long since disappeared), but moving forward with Python 3 has proven to be a significant challenge for ViewVC. A key dependency of ViewVC's support for Subversion repositories — Subversion's own Python language API bindings — have not at the time of this release yet achieved Python 3 support. So ViewVC 1.2 is a (hopefully short-lived) release line aimed at getting into users' hands previously unreleased features and improvements that have been collecting over the past decade before the project takes up Python 3 as a requirement.

### Configuration Override Section Syntax Change

ViewVC 1.2 changes the syntax of so-called configuration override sections from using a slash character (`/`) as the hierarchical separator to a pipe character (`|`). This allows references to root names that carry context in a more obvious way. Administrators should replace the slash characters in any viewvc.conf section names with pipe characters. For example:

>     [root-project1/options]
>     authorizer = forbidden

>     [root-project1/authz-forbidden]
>     forbidden = private

…should now be changed to:

>     [root-project1|options]
>     authorizer = forbidden

>     [root-project1|authz-forbidden]
>     forbidden = private

### Templates

This section describes template variable changes introduced in this release. See the Template Authoring Guide for the current set of variables available to each templates.

ViewVC 1.2 ships with two supported template sets now, "default" (which is based on the ViewVC 1.1 "viewsvn" contributed template) and "classic" (which derives from the ViewVC 1.1 default template). As such, the default value of the `template_dir` configuration option is now "templates/default" rather than merely "templates".

Variable | Location | Changes
--- | --- | ---
home_href | all templates | added
gbbox | graph.ezt | added
gflip | graph.ezt | added
gleft | graph.ezt | added
gmaxtag | graph.ezt | added
graph_action | graph.ezt | added
graph_hidden_values | graph.ezt | added
gshow | graph.ezt | added
opt_gbbox | graph.ezt | added
opt_gflip | graph.ezt | added
opt_gleft | graph.ezt | added
opt_gmaxtag | graph.ezt | added
opt_gshow | graph.ezt | added
dirs_shown | directory.ezt | added
entries.is_binary | directory.ezt | added
entries.is_viewable_image | directory.ezt | added
row_limit_reached | directory.ezt | added
roots.ago | roots.ezt | added
roots.author | roots.ezt | added
roots.date | roots.ezt | added
roots.log | roots.ezt | added
roots.log_href | roots.ezt | added
roots.rev | roots.ezt | added
roots.short_log | roots.ezt | added
roots_shown | roots.ezt | added
changes | diff.ezt | renamed to diffs.changes
changes.have_left | diff.ezt | renamed to diffs.changes.have_left
changes.have_right | diff.ezt | renamed to diffs.changes.have_right
changes.left | diff.ezt | renamed to diffs.changes.left
changes.line_info_extra | diff.ezt | renamed to diffs.changes.line_info_extra
changes.line_info_left | diff.ezt | renamed to diffs.changes.line_info_left
changes.line_info_right | diff.ezt | renamed to diffs.changes.line_info_right
changes.line_number | diff.ezt | renamed to diffs.changes.line_number
changes.right | diff.ezt | renamed to diffs.changes.right
changes.type | diff.ezt | renamed to diffs.changes.type
diffs | diff.ezt | added
diffs.anchor | diff.ezt | added
diffs.changes.columns.line_number | diff.ezt | added
diffs.changes.columns.segments.text | diff.ezt | added
diffs.changes.columns.segments.type | diff.ezt | added
diffs.changes.columns.segments | diff.ezt | added
diffs.changes.columns | diff.ezt | added
diffs.changes.gap | diff.ezt | added
diffs.changes.segments.text | diff.ezt | added
diffs.changes.segments.type | diff.ezt | added
diffs.changes.segments | diff.ezt | added
diffs.diff_block_format | diff.ezt | added
diffs.left.ago | diff.ezt | added
diffs.left.author | diff.ezt | added
diffs.left.log | diff.ezt | added
diffs.left.size | diff.ezt | added
diffs.right.ago | diff.ezt | added
diffs.right.author | diff.ezt | added
diffs.right.log | diff.ezt | added
diffs.right.size | diff.ezt | added
hide_legend | diff.ezt | added
left | diff.ezt | renamed to diffs.left
left.annotate_href | diff.ezt | renamed to diffs.left.annotate_href
left.date | diff.ezt | renamed to diffs.left.date
left.download_href | diff.ezt | renamed to diffs.left.download_href
left.download_text_href | diff.ezt | renamed to diffs.left.download_text_href
left.path | diff.ezt | renamed to diffs.left.path
left.prefer_markup | diff.ezt | renamed to diffs.left.prefer_markup
left.rev | diff.ezt | renamed to diffs.left.rev
left.revision_href | diff.ezt | renamed to diffs.left.revision_href
left.tag | diff.ezt | renamed to diffs.left.tag
left.view_href | diff.ezt | renamed to diffs.left.view_href
right | diff.ezt | renamed to diffs.right
patch_href | diff.ezt | added
raw_diff | diff.ezt | renamed to diffs.changes.raw
right.annotate_href | diff.ezt | renamed to diffs.right.annotate_href
right.date | diff.ezt | renamed to diffs.right.date
right.download_href | diff.ezt | renamed to diffs.right.download_href
right.download_text_href | diff.ezt | renamed to diffs.right.download_text_href
right.path | diff.ezt | renamed to diffs.right.path
right.prefer_markup | diff.ezt | renamed to diffs.right.prefer_markup
right.rev | diff.ezt | renamed to diffs.right.rev
right.revision_href | diff.ezt | renamed to diffs.right.revision_href
right.tag | diff.ezt | renamed to diffs.right.tag
right.view_href | diff.ezt | renamed to diffs.right.view_href

## Upgrading From ViewVC 1.0

This section discusses how to upgrade ViewVC 1.0.x to ViewVC 1.1.x.

### root_as_url_component Now Enabled by Default

In ViewVC 1.1, the `root_as_url_component` configuration option is now enabled by default. This option causes ViewVC URLs to be of the form `…/root-name/path-in-root[?…]` instead of `…/path-in-root/?root=root-name[&…]`, and makes for a much more intuitive user experience, navigation-wise, when ViewVC is serving up multiple version control repositories. When in this mode, ViewVC will automatically perform the obvious redirection for URLs which have a `root=` CGI parameter.

Unfortunately, there's a catch. Older URLs for the default root (specified by the `default_root` configuration option) were optimized to not include the `root=` CGI parameter. This means they look unfortunately similar to the newer root-in-the-path URL format, and ViewVC will not attempt to redirect them. But ViewVC won't be able to handle them, either. So, old-style default-root URLs, when aimed at a ViewVC for which the `root_as_url_component` option has been subsequently enabled, will result in an error. If you need to preserve the functionality of those old URLs, you'll need to either disable `root_as_url_component`, or use some other mechanism (like server URL rewriting) to morph them into compliance with the new URL format.

### Path-Based Authorization / Forbidden Modules

ViewVC 1.1 introduces a new pluggable authorization (authz) subsystem which gives administrators greater control over the accessibility of the information ViewVC displays in its output. ViewVC provides a number of working authz modules and a framework for configuring them. But of specific interest to folks upgrading from ViewVC 1.0 is that one of these new modules has replaced the handling of forbidden modules. As such, the `forbidden` configuration option now lives under the configuration section specific to that authz module.

Migrating your existing configuration of forbidden modules should be fairly straightforward:

1. In the new "authz-forbidden" section of viewvc.conf, set the `forbidden` option to the same value as the `forbidden` option in your ViewVC 1.0.x configuration's "general" section.
2. In the new "authz-forbiddenre" section of viewvc.conf, set the `forbiddenre` option to the same value as the `forbiddenre` option in your ViewVC 1.0.x configuration's "general" section.
3. Finally, ensure that that the new `authorizer` option is set to either "forbidden" or "forbiddenre", depending on which of those you were using in ViewVC 1.0.x.

Of course, you might wish to take advantage of another of the provided authz modules. Or, you might wish to write a brand new one for your purposes. The flexibility is yours.

Known Issues:

- ViewVC does not provide an authentication framework. It does, however, inherit authenticated usernames as determined by the HTTP server (Apache, e.g.) via the CGI environment. So, any authorization module that assigns privileges based on usernames will work only if ViewVC is deployed in a way that requires successful authentication (as opposed to allowing anonymous access).
- Currently, the root listing view only honors the global or vhost-specific configurations, not any root-specific configuration. In the event that ViewVC is using root-specific configuration for its authorization stuffs, this may cause either the unintended leak of root names to users or the inability to see roots at all. However, for root-specific ViewVC views, all configuration — include root-specific configuration — is honored. If you are concerned about leaking root names in the root listing view, you might consider disabling that view altogether by removing `roots` from the list of views specified in the `allowed_views` configuration option.
- The experimental module which allows ViewVC to serve up views of remote Subversion repositories is not yet fully integrated with the authorization subsystem, and almost certainly will leak privileged data. Sorry. That's (one reason) why it's experimental.

### Syntax Highlighting

ViewVC 1.0.x supports syntax highlighting provided by multiple third-party highlighting engines, including GNU enscript, GNU source-highlight, highlight, php, and py2html. Unfortunately, each of those integrations worked differently than the others. Some supported line numbers, some didn't; some were under active development and recognized newer languages; some weren't; each had its own set of CSS stylations that needed to be customized; etc.

In ViewVC 1.1, we've dropped support for all of those integations in favor of a single integration with Pygments, a Python-module-based syntax highlighting engine. As such, the configuration options for the various other engines (both those that enabled the integration and those that specified the locations of the third-party tools) have been removed from ViewVC, and have been replaced by a single new configuration option: `enable_syntax_coloration`.

The list of removed options is as follows:

- options/enscript_path
- options/highlight_convert_tabs
- options/highlight_path
- options/markup_line_numbers
- options/php_exe
- options/py2html_path
- options/use_enscript
- options/use_highlight
- options/use_pagesize
- options/use_php
- options/use_py2html

### Checkin Database

ViewVC 1.1 introduces to the `cvsdbadmin` and `svndbadmin` tools a new "purge" operation, which allows you to remove all the information related to a given root from your checkins database (without disturbing the information associated with other roots). Likewise, the "rebuild" command in those tools now implies a "purge" followed by an update.

As a related change, the `svndbadmin` program's "rebuild" subcommand has had its purpose become more defined. It no longer accepts a revision argument, and therefore can now only be used to completely rebuild the entirety of the checkin database information for a Subversion repository (instead of being able to only update the information related to single Subversion revision). For per-revision updating, use `svndbadmin update` and provide a revision (or revision range). And to get the previous rebuild-a-revision effect, pass the new `--force` option to `svndbadmin update`.

In other words, where you once did this:

>     $ svndbadmin rebuild /path/to/repository 1234

you now need to do this:

>     $ svndbadmin update /path/to/repository 1234 --force

To enhance the performance of the new "purge" operation, ViewVC 1.1 introduces some slight changes to the checkin database schema. If you use the `make-database` tool to (re)create your checkins database, it will by default employ the new database schema. This should cause the database to be virtually unusable by previous versions of ViewVC, and that's by design. If, however, you need to (re)create your checkins database and you require compatibility with previous versions of ViewVC or ViewCVS, simply pass the "--version=1.0" option to the `make-database` script. Note that your "purge" and "rebuild" operations could be abysmally slow, though, as that version of the database schema is not optimized for those operations.

### Configuration Options

This section covers changes to configuration options not already discussed in other sections pertaining to this upgrade.

In ViewVC 1.1, a new "utilities" section was added to the viewvc.conf file. All the options used for configuring the locations of various helper applications that ViewVC uses which were previously scattered throughout the configuration file are now all centralized in this one new section. To accomplish this, the following options were added:

- utilities/cvsgraph
- utilities/cvsnt
- utilities/diff
- utilities/rcs_dir
- utilities/svn

…and these were removed:

- general/cvsnt_ext_path
- general/rcs_path
- general/svn_path
- options/cvsgraph_path

All the options which governed which ViewVC views were enabled have been consolidated into a single new option. This new option:

- options/allowed_views

…replaces these, which have been removed:

- options/allow_annotate
- options/allow_markup
- options/allow_tar

ViewVC now honors the "svn:mime-type" property stored on Subversion-versioned files as the primary source of MIME type determination (before falling back to name-based MIME mappings and such). However, this can negatively affect the viewability of certain files — especially images — whose "svn:mime-type" properties are set incorrectly, such as will happen if Subversion itself merely determines that the file isn't human-readable and uses the "application/octet-stream" MIME type to record this determination. To make ViewVC not honor the "svn:mime-type" property value, set the `svn_ignore_mimetype` configuration option.

Speaking of MIME types, the option `mime_types_file` is now `mime_types_files`, as it now carries multiple paths to MIME mappings files, ordered by preference.

The `use_rcsparse` option was moved from the "general" section to the "options" section.

The `log_sort` option's value "cvs" has been renamed to "none" (for general application across all supported version control systems).

Custom sections which define per-virtual-host configuration option overrides must now have their names prefixed with "vhost-". Also, instead of a hyphen (-) between the virtual host name and the base configuration section being overridden, now there should be a forward slash character (/). For example, the following configuration which was valid in ViewVC 1.0 is no longer valid:

>     [vhosts]
>     all = viewvc.*

>     [all-options]
>     allowed_views = annotate, diff, markup, tar

This now needs to be written like so:

>     [vhosts]
>     all = viewvc.*

>     [vhost-all/options]
>     allowed_views = annotate, diff, markup, tar

The following is a grab-bag of additional new options:

- options/hide_errorful_entries
- options/mangle_email_addresses

### Templates

This section describes template variable changes introduced in this release. See the Template Authoring Guide for the current set of variables available to each templates.

One notable change in ViewVC 1.1 is that the markup.ezt and annotate.ezt templates have been combined into a single file.ezt template.

Also, the configuration options under the `[templates]` section are now paths relative to the configured template directory (either the value of the `options/template_dir` option, or the default "templates" directory), instead of being relative to the configuration location.

Variable | Location | Changes
--- | --- | ---
rootpath | all templates | added
change_root_action | all templates | removed
change_root_hidden_values | all templates | removed
roots | all templates except roots.ezt | removed
roots.path | roots.ezt | added
queryform_href | diff.ezt, file.ezt, graph.ezt, log.ezt, log_table.ezt, query_form.ezt, revision.ezt, roots.ezt | added
tarball_href | diff.ezt, file.ezt, graph.ezt, log.ezt, log_table.ezt, query_form.ezt, query_results.ezt, revision.ezt, roots.ezt | added
properties | directory.ezt, file.ezt | added
properties.name | directory.ezt, file.ezt | added
properties.undisplayable | directory.ezt, file.ezt | added
properties.value | directory.ezt, file.ezt | added
diff_format_hidden_values | diff.ezt | now is an iterable list of objects with .name and .value attributes
diff_type | diff.ezt | new value: `f`
date_left | diff.ezt | renamed to `left.date`
path_left | diff.ezt | renamed to `left.path`
rev_left | diff.ezt | renamed to `left.rev`
tag_left | diff.ezt | renamed to `left.tag`
date_right | diff.ezt | renamed to `right.date`
path_right | diff.ezt | renamed to `right.path`
rev_right | diff.ezt | renamed to `right.rev`
tag_right | diff.ezt | renamed to `right.tag`
annotate_href | diff.ezt | removed, use `right.annotate_href` instead
left.annotate_href | diff.ezt | added
left.download_href | diff.ezt | added
left.download_text_href | diff.ezt | added
left.prefer_markup | diff.ezt | added
left.revision_href | diff.ezt | added
left.view_href | diff.ezt | added
right.annotate_href | diff.ezt | added
right.download_href | diff.ezt | added
right.download_text_href | diff.ezt | added
right.prefer_markup | diff.ezt | added
right.revision_href | diff.ezt | added
right.view_href | diff.ezt | added
right.view_href | diff.ezt | added
dir_paging_hidden_values | directory.ezt, , dir_alternate.ezt | now is an iterable list of objects with .name and .value attributes
entries.log | directory.ezt, dir_alternate.ezt | now always contains untruncated log message
entries.short_log | directory.ezt, dir_alternate.ezt | added
search_re_hidden_values | directory.ezt, dir_alternate.ezt | now is an iterable list of objects with .name and .value attributes
search_tag_hidden_values | directory.ezt, dir_alternate.ezt | now is an iterable list of objects with .name and .value attributes
pathrev_clear_hidden_values | log.ezt, log_table.ezt, directory.ezt, dir_alternate.ezt | now is an iterable list of objects with .name and .value attributes
pathrev_hidden_values | log.ezt, log_table.ezt, directory.ezt, dir_alternate.ezt | now is an iterable list of objects with .name and .value attributes
annotate_href | log.ezt, log_table.ezt | renamed to `head_annotate_href`
diff_form_hidden_values | log.ezt, log_table.ezt | now is an iterable list of objects with .name and .value attributes
download_href | log.ezt, log_table.ezt | renamed to `head_download_href`
download_text_href | log.ezt, log_table.ezt | renamed to `head_download_text_href`
log_paging_hidden_values | log.ezt, log_table.ezt | now is an iterable list of objects with .name and .value attributes
logsort_hidden_values | log.ezt, log_table.ezt | now is an iterable list of objects with .name and .value attributes
prefer_markup | log.ezt, log_table.ezt | renamed to `head_prefer_markup`
view_href | log.ezt, log_table.ezt | renamed to `head_view_href`
rss_link_href | query.ezt, rss.ezt | added
query_hidden_values | query_form.ezt | now is an iterable list of objects with .name and .value attributes
jump_rev_hidden_values | revision.ezt | now is an iterable list of objects with .name and .value attributes
num_changes | revision.ezt | added

## 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/dir_pagesize
- options/log_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.short_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 ViewCVS 0.9.x.

### 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.

Variable | Location | Changes
--- | --- | ---
headers | directory.ezt | removed; headers are now listed explicitly in the template, rather than made available through a list.
rows.cols | directory.ezt | removed; was used in conjunction with the headers variable to control the column displays. This is now controlled explicitly within the templates.
rows.span | directory.ezt | removed; was used in conjunction with the headers variable to control the column displays. This is now controlled explicitly within the templates.
rev_in_front | directory.ezt | removed; 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.
rows.attic | directory.ezt | removed; 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.
rows.hide_attic_href | directory.ezt | removed; 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.