Revision Problems Summary

This page is intended to become a list (only) of the various problems and proposed solutions associated with changes/revisions on TWiki. The purpose is to allow interested people to focus on the problems and proposed solutions and select an appropriate set of solutions which might be implemented.

The original page has now been copied to RevisionProblemsSummaryDiscussion, now trying to refactor and summarize this page.

Problems I think are already covered on other pages

• Getting change notification with no changes, not even an increase in revision number (change reverted within one hour).

• Getting change notification with an increase in revision number, but no indication anywhere, not even in the diff (addition or deletion of (horizontal)spaces which don't break a word in two or combine two words into one).

• Getting change notification with an increase in revision number, and hard to find indication in the diff (addition or deletion of vertical spaces (which don't break a paragraph or combine two paragraphs into one)).

• Changes recorded for "maintenance activities" like:
  • Renames
  • Moves (to a different web)
  • Changes to a form field

• Changes recorded for "uninteresting" changes, like:
  • Spelling or minor grammar corrections *

Note: Some people may need (want) to review minor changes.

Proposals

1. indicating updated topics via links (ex: every link on this page to a topic non-trivially updated in, say, the last 24 hrs, would have a "new" indicator of some sort;
2. making it easy to see page diffs (current block diffs displays make it difficult to see what's been changed) (WordStyleDiffs);
3. combining all of the above in a usable interface, so that each logged in user can see the changes since last visit (this problem is well-explained in a quote on the DevOpinionPoll memo)
4. Making changes more obvious by using Word style diffs
5. Distinguishing between various levels of revisions in the various means of notification
   • Typo fixes
   • Minor changes
   • Major changes

• Who classifies the change? How? (I think it needs to be the "author" of the change, and done with a selection of buttons when the author saves the changed page.)

• Which changes should be included in the email notification?
• Should there be separate WebChanges pages for minor and major changes? (Is there something already done along these lines?

Note that Codev (only) already has a change -- there are now "Changes" and "Detailed" links. Changes calls http://twiki.org/cgi-bin/changes/Codev, Detailed calls http://twiki.org/cgi-bin/view/Codev/WebChanges. Changes (on the Codev web) shows major changes only, Detailed shows major and minor changes. Changes on the other webs calls http://twiki.org/cgi-bin/view/<webname>/WebChanges which means that it shows major and minor changes.

The TWiki templates can be modified to get behavior just like the Codev web (i.e., no code change required.

Problems that might not be covered on other pages (yet)

Dealing with changes on large pages including included pages

• See ChangesOnPagesWithIncludes. When trying to see what changed on TWikiDocumentation I was overwhelmed by the size of the diff (and the time it took to load the original page before I could even request the diff).

Suggestions for possible solutions:

• A means to request a diff before the entire page is loaded (diff and other view controls on a frame at the top of a page?)

• A hierarchical diff something along these lines:
  • When a diff is displayed for a document which includes other documents, don't display changes in the included document(s), but only display a diff of the "master" document's text, in other words, a diff of the include statements, not the included documents. The slight wrinkle is that the diff program should do a diff on the included documents to recognize which included documents have changed (or determine this by some other means) and list those for the reader who can view them at his option.

An alternate potential workaround is to avoid making such large pages this way, but instead include a (hidden) tag on each page so that the large document can be viewed using the BookView version of search (assembled on the fly, so to speak). (Is there a way to control the order of found pages? Do I have to put a slightly different (hidden) tag on each page, like <!--TWikiDocumentation.Page01-->, ....Page02, ...?)

Diffs Without Enough Context to Identify

I don't know if this is covered somewhere else (even in something I might have written), but this seems to be a good example of a problem:

The diff from version 1.30 to 1.31 of TextFormattingRules looks like below (approximately -- I couldn't format exactly the same). The only way I could find the actual change was to go back to Rev. 1.30, search for #SquareBrackets, and then view 1.31 and see which instance had been deleted. (Actually, once I saw the first instance in 1.30 I assumed that it was the one deleted.)

 Changed: 
<
< #SquareBrackets 
>
>

-- RandyKramer - 21 Jan 2002 Refactoring started

Randy: I haven't been on much this month. Rereading this, I believe we should definitely merge it into ChangesProject - forgetting the descriptive value of titles for the moment, just seeing whether the Project categories are practical. The existing organization - headings - of ChangesProject - and all the others - can be totally rearranged. The one thing is to try to get a clear real-world definition of each Project area. Like, Changes is really part of all the other Projects, but it's also, from the user view, a very distinct subset: finding out when to look at what. If that holds up, ChangesProject works... Same for the others. (I just added ModularizationProject!?)

-- MikeMannix - 28 Dec 2001

Added new section [#Diffs_Without_Enough_Context_to_Identify]. PS: I recognize that this page overlaps with the ChangesProject page -- at some point refactoring should probably combine the two pages (although the focus may be slightly different).

-- RandyKramer - 25 Jan 2002