From NSDLWiki

Versioning

Design | Discussion | Status | Testing

Contents [hide] 1 Versioning 1.1 Overview 1.2 Configuration 1.3 Version Metadata and Uploads/Links 1.3.1 Uploads 1.3.2 Links 1.4 Reason for Change log message for Publish 1.5 View Record 1.5.1 Base 1.5.2 Extension 1.6 List of Versions 1.6.1 Base 1.6.2 Modification 1.7 Revert to a Version

Overview

This page describes the proposed design for versioning. The work described on this page will be committed to the Fez trunk. Major portions of the work may be committed in different revisions. For example, Matt Painter's work along with the configuration changes will likely be committed first. Then enhancements, such as the Reason for Change log, which build on this work will be committed in a later revision.

If you wish to comment or make suggestions related to this design, please send them to the fez-developers@lists.sourceforge.net mail list.

Basis of Work

This work is based off the versioning work that Matt Painter made available on the Fez Add-ons page. When you see 'Base' in this page, it is referring to this work.

The following sections describe modifications and extensions of this work.

Configuration

Two new configuration settings were added to Administration->Site Configuration->Versioning Settings

Enable Versioning for Attached Files and External Links = On | Off  (default=Off)
Interval Between Fedora Versions (default 30 seconds)

APP_VERSION_UPLOADS_AND_LINKS indicates whether uploaded files and external links should be versioned. It can have one of two possible values.

1. On - set versioning to true for all uploaded and external link datastreams
2. Off - set versioning to false for all uploaded and external link datastreams (default)

The default setting is consistent with the current behavior of Fez.

Interval Between Fedora Versions is the minimum amount of time in seconds between amalgamated versions of datastreams of a record that are deemed to correspond to an atomic Fez operation. If this value is set too high, the filtered list of version times may not display legitimate edits. If the value is set too low, the filtered list may include times that correspond to updates of individual datastreams.

Two new configuation properties will be added to class.configuation.php:

APP_VIEW_VERSIONS_ROLES = list of roles (default="" which is ADMIN only)
APP_REVERT_VERSIONS_ROLES = list of roles (default="" which is ADMIN only)
APP_VIEW_VERSIONS_ROLES_ID = list of role ids (default="" which is ADMIN only)
APP_REVERT_VERSIONS_ROLES_ID = list of role ids (default="" which is ADMIN only)

Appropriate canViewVersions() and canRevertVersions() functions will be added to class.record.php based on these roles. This is consistent with handling of other APP_*_ROLES lists.

The drop list of versions will only be displayed in the view record when the user's role is on the list of APP_VIEW_VERSIONS_ROLES. If the user's role is also on the APP_REVERT_VERSIONS_ROLES list, the user will also be able to make one of the older versions the current version. In this case, the older version will be copied and saved as the latest version, thus allowing versions between the older version and the most recent version to be maintained.

Rev 1897 includes all configuration except APP_REVERT_VERSIONS_ROLES and APP_REVERT_VERSIONS_ROLE_IDS. Reverting to a previous version was not part of this revision.

Version Metadata and Uploads/Links

Metadata versioning is controlled by the VERSIONABLE static value set in the XSD that controls the creation of the datastream for the metadata. Thus, some metadata datastreams in a record may be versionable while others may not.

When Versioning is ON, the following behaviors can be expected...

Uploads

• the trigger for a new version is uploading a file with the same name as an existing uploaded file
• non-admin users can delete, but not purge uploaded files
• admin users can delete or purge uploaded files

Links

• the trigger for a new version is changing the URL, but not changing the Description field
• links are deleted (not purged) when the user clears or changes the value of the Description field

Rev 1897 includes versioning of metadata, attached files, and external links.

Reason for Change log message for Publish

When the user selects to publish a record, a message box will be presented allowing the user to enter a reason for the change to the record. This reason will be added to the <premis:eventDetail> as -- Reason: user's message. For example:

<premis:eventDetail>Published by E. L. Rayle -- Reason: Updated author to 
include all authors</premis:eventDetail>

Rev 1897 does not include Reason for Change logging.

View Record

Base

A drop menu is added to the view record template which presents the list of versions to Admin users. See below how this list is generated. This section deals with visual presentation only.

Extension

Changes to the appearance of the View Record screen include:

• The drop menu will include the Reason for Change log message for each version if available.

• When viewing any version but the current version, change the background color of the info box area to visually indicate that this isn't the current state of the record.

• In the info box area, include the date and reason for the changes of the version being shown.

• When viewing any version but the current, add a workflow that performs the revert to this version.

Rev 1897 includes View Record changes described here.

List of Versions

Base

A single configuration property (APP_PHANTOM_VERSION_TIME_INTERVAL) was added to set the amount of time that should pass between Fedora versions to be part of the list of versions. Fedora versions that are closer together than this setting are typically part of the same commit process which may have written multiple datastreams to Fedora.

The list of versions has two filter modes:

• Filtered - shows only versions that match the APP_PHANTON_VERSION_TIME_INTERVAL
• Full - shows all versions

Modification

Exploring several possibilities:

• No change. Use the APP_PHANTOM_VERSION_TIME_INTERVAL to determine the list of versions.

• When committing a change to Fedora, use the Reason for Change log message as the Fedora logMessage for all datastream modifications related to a single publish command. Then use the Fedora logMessage as the reason when showing the list of versions. The determination of what constitutes a version would continue to be generated based on APP_PHANTOM_VERSION_TIME_INTERVAL.

• Getting the list of version dates from the premis index in MySQL. Only rows where pre_detail begins with "Published" will be selected. Dates will be those in the pre_date field. I need to confirm that these date-time stamps reflect that latest date-time stamp of all updates to the record made as part of the publish process. This is my first choice since "Publish" represents major changes to the records.

If the last option proves viable, I will most likely extend the filter list to add a third option:

• Published - shows versions that correspond to the publish date-time stamps.

Rev 1897 includes the base implementation for listing versions. Listing by pubish date was not part of this revision.

Revert to a Version

When a record is reverted to a previous version, the values of the older version will be saved as a new version. This will allow the changes between the reverted version and the version that was current at the time of the revert to be maintained. The reverted values will be in the record versioning history twice, in the original date-time location and in the current version.

Rev 1897 does not include reverting to a previous version.