Tags:
create new tag
view all tags

Abstract

I want to create a system to track revision information about software projects I am maintaining. This information includes (but not limited to):
  • Revision tag (e.g. 2.6.7)
  • Originating revision (or multiple if a merge)
  • Summary of what was done
  • Status of revision (e.g., started, testing, complete)
  • Author(s) involved
  • Bugzilla #'s of what is fixed, enhanced, or generally addressed in some way
  • Is it stable?
  • Is it available?
  • General notes in free-form TWiki
  • Detailed notes in free-form TWiki

This sort of system could certainly be implemented using a database or relying on the RCS system to store and retrieve revision information, but a database solution seems a bit overkill and an RCS system would be inflexible since you can't easily fix errors or change the information once it is stored.

On the other hand, using TWiki would allow me to edit revision information piecemeal while I am creating a revision. If I make a mistake, I can easily go back and fix it. The information is plain simple text so its painless to maintain revision information.

Therefore I am proposing to make a TWiki plugin that allows developers to capture all of the above information for revisions of software being produced (it is not limited to just software though). The plugin will be responsible for the following:

  • Provide a mini-language for specifying information about each revision (using % tags).
  • Allow developer to use a separate topic for each revision or document several revisions in a single topic.
  • Provide a % tag to display a summary table of all the revisions for a project.
  • Have a % tag to display to differences between any two revisions, provided they are logically connected.
  • Facilitate other activities related to revisions; e.g. generating a page where setup programs can be downloaded for all "stable" revisions.
  • Integrate with Bugzilla

Revision Information Topic

All revision information is stored in one or more topic pages. The number of pages and quantity of information in each page is completely arbitrary. However I would probably use a topic like EmacRev4dot4 to contain all the revisions for version 4.4.

Whenever changes are saved to a revision information topic, the plugin will update a "master" text file for the project with summary information and links with page anchors to revision information in the topic being saved. The master file can then be used to generate a revision summary for a project quickly and efficiently. (Assuming that all revision information is entered via TWiki.) A master text file can reside with the web as an internal file starting with an _.

Here is an example of a revision information topic page:

TWiki code

%REVPROJECT{EMAC}%

%REVRECORD{4.4.10}%
prev        4.4.10
authors     Andy Steve
status      Started
summary     Improved secondary positioning function.
job         5699
bugzfixed   56 44 102 89
bugzenh     90 92
setupfile   setup_4-4-10.exe
avail       yes
stable      no

%REVNOTES%
   * Added some fields in secondary positioning step
   * Remove module XYZ

%REVDETAILS%
   * Very detailed notes; not necessary to show in revision diffs.

What it looks like

EMAC Revision 4.4.10

Revision Record
Key Value
Prev. Rev. 4.4.9
Author(s) Andy, Steve
Status Started
Summary Improved secondary positioning function.
Job # 5699
Bugszilla Fixed 56, 44, 102, 89
Bugszilla Enhanced 90, 92
Available? Yes
Stable? No
Setup File (link to attach.)

General Notes
  • Added some fields in secondary positioning step
  • Remove module XYZ

Detailed Notes
  • Very detailed notes; not necessary to show in revision diffs.

Revision Summary Table

A summary of revision information for a project can be displayed using the %REVSUMMARY{EMAC}% tag. This instructs the plugin to read the master project file and display its contents appropriately.

Here's an example of a revision summary table in use:

TWiki code

%REVSUMMARY{EMAC}%

What it looks like

Rev Date Status Summary Stable? Link
4.4.10 Mar-01, 2004 Done Improved secondary positioning step. Yes More
4.4.11 Mar-05, 2004 Started Bug fixes.   More
4.5.0 Mar-10, 2004 Done Added Linux support. No More

RevisionTrackerPlugin codes

Tag Description
%REVPROJECT{project-name}% Specifies the project name to which following codes are applied.
%REVRECORD{revision-tag}% Specifies the revision tag for information following it.
%REVNOTES% Marks the beginning of notes that apply to the revision.
%REVDETAILS% Marks the beginning of detailed notes for the revision.
%REVSUMMARY{project-name}% Displays the revision summary for a project.

This is a work in progress!

-- AndrewJoseph - 17 Mar 2004

Andrew, everything you want can be done using TWiki Forms and the FormQueryPlugin, or, by jumping through some hoops, by the basic SEARCH mechanism in TWiki itself. You shouldn't need another plugin.

-- CrawfordCurrie - 18 Mar 2004

I will check into this. That's part of the reason why I posted my requirements here to see if it could be done using existing methods and/or plugins. Thanks for the advice.

-- AndrewJoseph - 18 Mar 2004

WebForm
TopicClassification PluginBrainstorming
TopicSummary Plugin for tracking revision information about software projects.
InterestedParties

RelatedTopics

Edit | Attach | Watch | Print version | History: r5 < r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r5 - 2004-03-23 - AndrewJoseph
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.