Revision Problems Summary

This page is intended to become a list (only) of the various problems associated with revisions on TWiki. The intent would be to also list (and possibly summarize) existing proposals to fix the problems and new proposals as appropriate. The purpose would be to allow interested people to focus on the problems and proposed solutions and select an appropriate set of solutions which might be implemented.

This page is very rough at this time, contributions are solicited. I'd eventually like to do this in the style of the ProposedAdditionalButtons topic, with minimal discussion of the problems or solutions, and instead just lists of the problems, proposed solutions, and topics which explain the problem or proposed solution in more detail.

Initially, it is nowhere near that, and initially I am just "randomly" jotting down some problems I either know are covered on other pages or might not be. For example, I haven't started trying to search for the pages which discuss these problems.

Problems I think are already covered on other pages

From WebNotify

See the last notes from the bottom of the WebNotify page or ChangeNotificationWithNoObviousChanges.

• 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)).

From BrainstormScratchPad

I copied the following from BrainstormScratchPad (which may get archived or deleted):

Skip Changes Notification for maintenance tasks

Feature: Periodically a new system or web wide change is made which isn't reflected in the content of a page, but nevertheless is an edit to that page. It would be nice if these kinds of changes could be hidden from the WebChanges page.

Situation: For example the change date on TWikiUsabilityTesting is 31 Oct 2001 but the last change to the page content was 28 Sep 2001. The only change made on 31-Oct was to add a Topic Group and a meta-field.

Occasional updates of this nature for a page or two is not much of a problem, however it does become a problem when they happen web or system wide. At this moment WebChanges shows MikeMannix as having an incredibly productive day yesterday, answering over 40 seperate technical support questions.

This effectively means the WebChanges feature is broken, because now I must individually visit all of the topics I am participating in to search for "real" changes which may or may not be immediately apparent (did the last contributor append to the bottom of the page or embed a comment in the middle?).

Started: MattWilkie - 31 Oct 2001

Proposed Titles for this Topic:

Comments:

Matt, This was noted and discussed at some length in DevOpinionPoll (scroll down to the first block of italics). The issue is a little more complicated - there are four related concerns:

1. preventing notification of "trivial" changes;
2. 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;
3. making it easy to see page diffs (current block diffs displays make it difficult to see what's been changed);
4. 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)

This should all be broken out into its own base topic page and hooked up with the several relevant topics, like WordDiffs, etc. Read up and dive in if you have ideas!

-- MikeMannix - 31 Oct 2001

One item which might not be explicitly listed above is the problem of getting a notice of revision after a name change. (IMO, that should, at most, be noted as a minor change.)

Making changes more obvious by using Word style diffs

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?

Ahh, yes there is (and I am as blind as a bat) -- right at the top of every (view) page are the Changes and Detailed links (on the Codev web, only). Changes calls http://twiki.org/cgi-bin/changes/Codev, Detailed calls http://twiki.org/cgi-bin/view/Codev/WebChanges.

I did some testing -- Changes (on the Codev web) shows major changes only, Detailed shows major and minor changes. (I did not test the behavior of Changes on another web -- but, on Wikilearn, Changes calls http://twiki.org/cgi-bin/view/Codev/WebChanges which means that it should show major and minor changes.

Aside: I should be able to modify the template for Wikilearn to have Changes invoke the changes script (and add Detailed) to get behavior just like the Codev web.

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

Dealing with changes on large pages including included pages

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

Aside: This is more description than I would normally intend on this page -- I will move this stuff to another page after I "sleep on it" and think of a good topic name.

In the case of that particular page, which is made up of many included pages, some helps might include:

• 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, ...?)

-- RandyKramer - 03 Dec 2001

Randy, this is cool! This fits perfectly into ChangesThread -> ChangesProject: "Directory and summary page for Codev discussions related to tracking changes to topics: including notification methods, diffs displays, WebChanges, WebNotify"!! If you could see how this page fits as a kind of master page under ChangesProject, that'd be excellent. I'll work on both as well. Like, synergy about to go off...kinda!

-- MikeMannix - 03 Dec 2001

Mike, thanks!

I scanned the ChangesThread --> ChangesProject but will have to do so again to really get the drift of things. At present I see the need for three pages like the ProposedAdditionalButtons topic -- that one, this one, and one more to list all the proposed additions / changes to the TWiki shorthand (if I get ambitious enough to start such a page). For the time being, I will maintain them under their current titles (for the first two, anyway) ..., ahha!, now I understand, you've checked the ChangesProject checkbox under ProjectGroup to classify / tag this page. Looks good to me!

-- RandyKramer - 04 Dec 2001

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!?)

I'll also use a search to gather pages based on ProjectGroup, to replace the manual INCLUDES in place now. It just means tagging individual topics in one unde one or more Projects as quickly as possibly to make that useful.

I'm positive that, seen through, this will lead to a very useful view of TWiki dev, way more end-user oriented than the usual here, and practical and inspiring to everyone. But talk is cheap, and finishing is everything, isn't it?!

-- MikeMannix - 28 Dec 2001

Re:

But talk is cheap, and finishing is everything, isn't it?!

Yes, and I haven't finished, have I? (I feel especially bad about the second note from the WebNotify page -- it seems just totally screwed up! (I don't feel bad about saying so because I originated the note.))

Anyway, I'll try to fix that in the next day or so, using the following as my "scratch pad" version. (I'm currently at least slightly confused about what I was trying to say, so I'll start by restatin what I think I was trying to say, and then check the facts, or maybe I'll start with a question:

If someone edits a topic by only inserting or deleting (do I have to check each separately) blank lines (or horizontal white space), does the change show up in:

• The WebNotify email?
• The Changes page?
• The diff?

I think I'll create some test pages in the Codev web (VerticalWhitespaceChangeTestPage, HorizontalWhitespaceChangeTestPage), let them sit a day (so they are not new) and then start testing them with various changes and see the results. (I'd do this on the Test or Wikilearn webs, but they do not include all the change notification features of the Codev web, so I think the test will be more useful here. After the testing, I'll "archive" the pages somewhere else.)

Test Record:

• Created the pages yesterday (20010103), showed up on the various notifications today.
• At around 11:45 AM EST (20010104) I added two returns before the signature on the vertical test page, and two spaces before "diff" on the last line of the bulleted list on the horizontal test page. Neither change is visible on the revised page, as HTML strips out the duplicate spaces and returns. Going now to check other results.
• Both changed pages show up as new revisions on the WebChanges page (which is the same as the "Detailed" page -- http://twiki.org/cgi-bin/view/Codev/WebChanges).
• Both changed pages show up as new revisions on the Changes page (http://twiki.org/cgi-bin/changes/Codev).
• Viewing the diffs:
  • Horizontal: The diff shows no change between r1.1 and r2.2. If I go back to edit, the extra spaces are indeed there.
  • Vertical: The diff shows two extra ">"s on separate lines, but no text, so it seems to know something has changed (different than the result on the horizontal test). If I go back to edit, the extra returns are indeed there. I may try adding returns at two locations in the file just to see what happens (I'll wait until tomorrow to try that).

Next step:

• Tomorrow I'll confirm that both of these changes showed up in WebNotify. Update: They did.
• I may try adding returns at two locations in the file just to see what happens (I'll wait until tomorrow to try that). Update: Tried adding two returns (newlines) at three locations, got three "instances" of the double ">"s. Tried the same thing by adding two space in three different places in the horizontal test page -- revision number was incremented, but a diff shows no indication of a change.
• Then, as a slightly different test, I'll start to edit a page and then I'll use the back button to exit the page without editing to see if anything gets recorded as a change. I may try the same thing but going on to the preview and view steps before using the back button. Update: I'll bag this -- I tried using the back button from edit and nothing showed up anywhere, and, on further reflection, I find it very unlikely that it would unless I went as far as saving the edit.

I'm now moving the test pages to the Wikilearn web -- not sure how long I'll keep them there as there is no great value to them (like some other pages there).

Oops, nevermind, I don't have privileges to rename/move pages from Codev. If somebody else does they can feel free to move them to Wikilearn, otherwise I'll just leave them where they are (no big deal to me -- I was only trying to avoid cluttering Codev).

-- RandyKramer - 03 Jan 2002
Updated -- RandyKramer - 06 Jan 2002