TIP:            13
Title:          Web Service for Drafting and Archiving TIPs
Version:        $Revision: 1.26 $
Author:         Don Porter <dgp@users.sourceforge.net>
Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
State:          Accepted
Type:           Process
Vote:           Done
Created:        21-Nov-2000
Post-History:   

~ Abstract

This document proposes the TCT provide a service on the World Wide
Web for drafting and archiving TIPs and for providing TIPs in a
variety of formats.  A reference implementation is provided, and its
server requirements are outlined.

~ Background

It has been proposed (see [2]) that the TCT manage its projects and
procedures through a set of public documents known as Tcl Improvement
Proposals, or TIPs.  A format for TIPs has been approved (see [3]),
and although final approval of [2] is still pending, several TIPs
have been submitted, discussed, and revised, and a few have been
approved, so acceptance of TIPs in some form seems likely.

A prototype system has been provided by Donal
Fellows <fellowsd@cs.man.ac.uk>
[http://www.cs.man.ac.uk/fellowsd-bin/TIP/]
that delivers TIPs to visitors in a variety of formats.  However,
that system lacks archiving of each revision of each TIP, and
offers no interface (through the web or otherwise) for making
revisions to TIPs.  

The TIP format was inspired by the format used by the Tcl'ers
Wiki [http://www.purl.org/thecliff/tcl/wiki/].  The true power
of the Tcl'ers Wiki, though, is not in the particular format it
uses, but in the fact that it empowers the whole Tcl community to
contribute to a common set of resources.  The Tcl'ers Wiki
shows that valuable resources can arise out of the unrestricted
efforts of volunteers from the community.

~ Problems with Current TIP Infrastructure.

The Fellows web interface to the TIP Document Collection
[http://www.cs.man.ac.uk/fellowsd-bin/TIP/] offers valuable
browsing access to TIPs in a variety of formats.  It accomplishes
the important goal of making TIPs public.  However, it suffers from
two significant shortcomings:

   * Revisions are only possible through the TIP Editor:

   > Currently the only way to revise a TIP is to e-mail a new
     revision to the TIP Editor and wait for it to replace the old
     revision.  As more TIPs are submitted, and as each TIP is more
     frequently revised, this bottleneck will not be tolerable.

   > Discussion about TIPs currently takes place in Usenet newsgroups
     and on mailing lists, but because there is no easy access to
     revising the TIPs themselves, the new information and viewpoints
     arising in these discussions are not being folded back into the
     TIPs.  This means the TIPs are failing in their intended role to
     present a full history of an issue to later readers.  It also
     means newcomers to a TIP cannot receive a full briefing in one
     place, but must chase down discussions in mailing list and Usenet
     archives.  Few people do that, but instead repeat points already
     made.  The discussions about [6] reflect this problem.

   * An archive of each revision of each TIP is not maintained:

   > Although [2] refers to TIPs as being stored in a revision control
     system, probably a CVS repository, the Fellows TIP collection is
     not maintained in such a system.  Since a TIP is an archive of a
     public discussion of an issue, it is important to be able to
     access the history of changes to each TIP.

   > The ability to retrieve and restore earlier revisions of a TIP
     will be especially important if public revision is permitted, so
     that any TIP contents that are incorrectly removed, whether by
     accident or malice, can be restored.

~ Proposal

An improved system for archiving and revising TIPs is proposed:

   1. TIPs will be archived in a CVS repository.

   1. Anyone with the power to call a TYANNOTT vote will have commit
      access to this repository through either :pserver: or ssh
      access.  With this access, they will be able to revise any part
      (header or body) of any TIP (whether in ''State: Draft'' or
      not).  Everyone having this access will be trusted to modify
      TIPs only in conformance with the TIP format and the TCT
      procedures.

   1. An enhanced version of the Fellows TIP rendering engine will
      display an [[Edit]] link at the bottom of each TIP eligible
      for web-editing when that TIP is rendered in HTML.

   1. For any TIP in state Draft, and for which a vote is still
      pending, the [[Edit]] link will lead to an HTML form for
      submitting a revised TIP.  For other TIPs, no [[Edit]] link
      will appear, and an attempt to directly access web-editing of
      such a TIP will lead to a message stating that the TIP may not
      be edited through the web interface.

   1. The HTML editing form will display the TIP header, but will not
      make it available for editing.  The HTML form will require that
      an e-mail address be entered, and will allow a name to be
      entered as well.  A <TEXTAREA> will be initialized to hold the
      current TIP abstract.  A second <TEXTAREA> will be initialized
      to hold the current TIP body.  Users of the form will revise
      the abstract and the body, then submit the form.

   1. The TIP rendering engine will receive the revisions, and
      will use CVS client commands to merge the revisions with other
      revisions and commit the revised TIP to the TIP CVS repository.
      If a conflict occurs during a merge, the TIP body including the
      conflicts will be returned to the user in another HTML form to
      resolve the conflict.

    > Note that the CVS commit function of the TIP rendering engine
      implies that the CGI process in which the TIP rendering engine
      runs must have a user ID with commit access to the TIP CVS
      repository.

   1. In the revised TIP checked in to CVS the submitter of the
      revision will be added as an Author in the header of that TIP.

~ Reference Implementation

The modifications to the Fellows TIP rendering engine that add the
capabilities proposed above are now merged in.  The TIP rendering
engine is maintained and publically available
[http://sourceforge.net/projects/tiprender/].  To enable the
web-editing features, set the Tcl variable FEATURE(EDIT) to 1 in
the file config.tcl.  A working version of the proposed web service
is available at http://purl.org/tcl/tip/

For what it's worth, this TIP was created primarily within a web
browser, making revisions through the web interface provided by the
reference implementation.

One remaining shortcoming of the reference implementation is that it
provides no mechanism for uploading images to the TIP repository.
Images still need to be submitted through the TIP Editor, or
someone else with commit access to the TIP CVS repository.

~ Server Requirements

The reference implementation imposes the following requirements on a
server:

   1. The server provides an HTTP server that serves the public
      Internet, and supports the CGI interface.

   1. CVS client software must be installed on the server.

   1. The CVS repository containing TIPs must be on the server itself.
      This is due to a CVS limitation that ''loginfo'' scripts run on
      the machine housing the CVS repository, and the reference
      implementation uses a ''loginfo'' script to keep the TIPs
      presented through the web up to date with the commits to the
      repository.

   1. The CVS repository must offer commit access over the Internet
      using either :pserver: or ssh to everyone with authority to call
      a TYANNOTT vote.

   1. The user under which the HTTP server runs its CGI processes must
      have commit access to the TIP CVS repository.  This may have
      security implications.

~ Future Improvements

Once the TIPs are housed in a CVS repository, other services should be
easier to implement.  Another browsing interface could be provided
using cvsweb [http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/] to
allow anyone in the community to browse TIP history.  Another
''loginfo'' script could provide e-mail notices when a TIP is revised
to users who registered their interest in that TIP.

~ Acknowledgments

Thanks to Donal Fellows for the original TIP rendering engine and
his assistance merging in the changes.  Thanks to Brent Welch for
providing the server and his assistance getting it configured for
use.  Thanks to Mark Harrison for his assistance with managing
browser caching issues.

----

~ Comments from the TCT

 > It might be a good idea to make the Abstract into a seperate <textarea> and
   treat that specially; I've been applying the rule that a TIP's abstract
   should be a single paragraph (it is implicit in the way I generate XML for
   instance) and that would be much easier to enforce through this route.  It
   would also have the advantage of discouraging people from placing their
   whole rationale in the abstract - which I've seen in several first drafts by
   people who shall remain nameless - and prompting the creation of TIPs more in
   keeping with the general concept of publishable documents.

 > It would also be nice if each page had a way of viewing the TIP's revision
   history (by a link to a suitably setup CVSweb URL?)  The way that SourceForge
   does its CVS-over-the-web is very nice indeed...

 > ''Donal K. Fellows <fellowsd@cs.man.ac.uk>''

~ Author replies to comments

Some comments I see above, or received in e-mail:

 * ''Add a link to [3] on the edit page.  Display [3] in a new window.''

 > Link added.  I don't believe in deciding to open new browser windows for
   the user.  If the user wants to open the link in a new window, she knows
   how to do that.

 * ''Add an interface to create a new TIP''

 > For now, I'm trying to stick with the TIP procedures proposed in [2],
   where only the TIP Editor gets to create a new TIP, so all TIPs
   should still be originally submitted to him.  If the TCT rejects
   this proposal and adopts a different policy, we can revisit this
   question.

 * ''Browser caching makes it look like the edits were not made''

 > Based on advice from Mark Harrison and others, I've added HTTP
   headers that should prevent caching.  Please try it again.

 * ''I had the server time out on me''

 > That's troubling.  Can anyone seeing this problem provide any more
   information.  What were the circumstances, in detail?

 * ''Add links to an interface showing revision history''

 > Check out the [History] links at the bottom of the HTML rendered pages.
   Thanks to Donal Fellows for coding that up.  (OK, so we *did* reinvent
   CVSWeb.)

 * ''A separate <TEXTAREA> for the Abstract''

 > This is now implemented.  Please give it a try.

~ Copyright

This document has been placed in the public domain.