TWiki Release Tracker Plugin

The TWiki Release Tracker (aka TRT) plugin tells you exactly how your install differs from every production and beta release of TWiki.

Synopsis

This plugin provides an interface to show to what degree a TWiki installation is different from the distribution from which it was installed. After installing TWiki, many administrators make minor modifications to tweak its functionality or to apply patches. While the some adminstrators keep a patch log, alterations can still get forgotten about. Upgrading then poses a problem when adminstrators because their code changes get lost in the upgrade. This can make some users reticent about upgrading. Furthermore, because producing patches is normally a cumbersome process, users often don't package them and feed them back to TWiki.org.

This plugin provides a web-based environment to query the differences: users can walk around the installed code base, get a quick overview of what has changed by comparing the MD5 index of their installation with that of the distribution. Further screens provide a view to examine these in depth, with diffs as the output.

The command line environment provides a second route to the functionality and adds commands that give the user the ability to save the diffs as a composite patch file to be used to quickly refit their changes onto a new release; that same patch file can be shared with the community to accelerate TWiki development.

Further development

If you find it useful, please send me (Martin AT Cleaver.org) a note of thanks. Donations towards specifics for further development can be sent to the same paypal address.

TWikiReleaseTrackerPlugin Overview

Features and Benefits

• By generating a content identifier for every file in all TWiki distributions (core beta and release versions, plus all the plugins), the system advises where every file in your install has come from.
• By providing navigation from installation file content to distribution file content, the system provides the means to generate diffs from your install to a distro. This means that not only can you tell where your version is behind a distribution, but also shows you where you have altered your version. The downloadable diff provides the opportunity to feed back to the TWiki community the change you've made back, meaning for the patch owner less rework the next time TWiki is released and, for the community as a whole, better capture of changes leading to more progress .

How it works

The TRT centres on the concept of a unique CONTENT identifier - instead of identifying a file by its filename, identities are based on file content. This means that a file copied to another place has the same unique content identifier. The system used md5 signatures as the identifier.

TWikiReleaseTrackerPlugin is comprised of two parts:

1. a twiki plugin that provides a web interface to the API of the comparator. Unlike previous versions, this one includes in situ building of indexes for the local installation using the web interface.
2. a command line indexer that builds and saves indexes. This is used to generate the md5 files included in pub/TWiki/TWikiReleaseTrackerPlugin

Plugin Installation and Set up Instructions

1. Download the ZIP file from the Plugin web (see below).
2. Unzip TWiki:Plugins.EditTablePlugin.zip in your twiki installation directory. (This will facilitate sorting the table entries)
3. This plugin requires TWiki:Plugins.BuildContrib and TWiki:Plugins.DistributionContrib to run. If you do not have these two plugins installed, download and install them before proceeding.
4. Create a md5 index of your local installation by clicking here. (Repeat this step after modifying installation files to create new index.)
5. Test if the Plugin is correctly installed:
   • Check the TRTChangesFromDistribution topic and see that the %DIFFWIKI{}% is expanded into formated report.
6. For further customization of the default setup, see #Settings below.

Plugin Usage Instructions

Basic usage

Web usage

• The TRT is shipped with data about standard TWiki "Production Releases". By default, the TRTChangesFromDistribution topic automatically generates a report comparing your local installation against the standard TWiki distribution specified by the WIKIVERSION variable. Note: If you are running a "Beta Release," you will need to download the "beta.md5" file from TWiki:Plugins.TWikiReleaseTrackerPluginDev and attach it to your local version of the TWikiReleaseTrackerPlugin topic.
• To view the changes for a particular file listed in the report, click on the corresponding link in the "Status" column.

Command line usage

TWiki:Plugins.TWikiShellContrib

TWiki:Plugins.TWikiReleaseTrackerPluginCommands

Comparing differences between standard TWiki installations

Even before you have built the index for your own installation, you can use the TRT to determine what changes were made between standard TWiki distributions. For example, click here to compare TWikiRelease01Sep2001 and TWikiRelease01May2000 production releases. To compare other releases, simply select them from the From and To drop down menus and click the Go button. From the drop down menu, you can

Advanced usage - Setting custom report parameters

Using the form at the top of TRTChangesFromDistribution, you can override the defaults listed on this page. All parameters specified below can also be overridden on the URL line.

In other words, TRT parameters can be sourced from one of three places:

1. Defaults listed on the plugin home page
2. Parameters specified on the %DIFFWIKI{} line
3. Parameters recognised as a CGI.pm parameter (e.g. on the URL line)

Parameters to the %DIFFWIKI directive

Limitations

Issue	Future Plan	Impact
To compare specific file changes (FSCD = File Same, Content Different), you need to have pre-downloaded all of the releases.	My plan is to have the plugin pull them down as needed, but I need a web address for a specific twiki version / file; currently this is not available (partly due to the switch to subversion)	High - file mode not yet functional
The MD5 for specific releases (i.e. releases.md5) needs pregenerating.	Release the code (actually a merge for the TWiki:Codev.SharedCode) when I have cleaned it up	Low - releases are not very often
If you want an unspecified destination (to) or source (from) distro you must set the param to ","	check for undef, not ""	Medium - ugly non-obvious workaround available
The results are not sorted	sort them	Low - workaround available: Use table sort function
The underlying data structures could do with some optimisation	Review	Low - Page load is slow in some cases

Default Plugin Settings

• • Set SHORTDESCRIPTION = Plugin telling you how similar your install is to past releases of TWiki

See the Parameters section for descriptions of the rest of these:

• • Set STATUSFILTER = FSCD,FDCS,FDCM
  • Set FROM = localInstallation
  • Set TO = ,
  • Set FSCDFORMAT = | $relativeFile | FSCDCALLBACK (show diffs) | FSCDDIST |

Future plans

• Make the TRT detect inconsistent indexes and offer to regenerate the localInstallation md5 file if necessary
• Make test suite TWiki:Plugins.BuildContrib TestRunner compatible
• Make use of TWiki:Plugins.AttrsContrib
• Investigate why the -w flag to diff is necessary
• md5 files will be pulled from a server rather than distributed

Manifest

Plugin Info

Plugin Author:	TWiki:Main.MartinCleaver
Plugin Version:	13:39:17 09 November 2004 ('1.010')
Change History:
09 Nov 2004:	Documentation update, and minor bugfix for an error in the logs
24 Oct 2004:	Minor bugfixes and inclusion of TWiki:Plugins.TWikiReleaseTrackerPluginCommands
29 Aug 2004:	Documentation update (thanks to TWiki:Main.LynnwoodBrown)
25 Aug 2004:	Diff is now passed the -w flag to ignore whitespace changes
24 Aug 2004:	Bugfix when comparing two arbitrary versions
23 Aug 2004:	First standalone version, this no longer requires download of zips to do comparisons against
01 Aug 2004:	Initial version
TWiki Dependency:	Name Version Description TWiki::Contrib::Build >=1.000 Required. Needed for the plugin to build itself. TWiki::Contrib::DistributionContrib >=0.4 Required. Needed for the plugin to get information about releases and to fetch distribution versions of files
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.005
TWiki:Plugins/Benchmark:	GoodStyle nn%, FormattedSearch nn%, TWikiReleaseTrackerPlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/TWikiReleaseTrackerPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/TWikiReleaseTrackerPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/TWikiReleaseTrackerPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.MartinCleaver - 09 November 2004

If you have comments or questions, please put them at TWiki:Plugins.TWikiReleaseTrackerPluginDev