TIP #13: Web Service for Drafting and Archiving TIPs


TIP:13
Title:Web Service for Drafting and Archiving TIPs
Version:$Revision: 1.26 $
Authors: Don Porter <dgp at users dot sourceforge dot net>
Donal K. Fellows <fellowsd at cs dot man dot ac dot uk>
State:Accepted
Type:Process
Vote:Done
Created:Tuesday, 21 November 2000

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 TIP #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 TIP #3), and although final approval of TIP #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 at cs dot man dot ac dot uk> [1] 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 [2]. 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 [3] 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:

Proposal

An improved system for archiving and revising TIPs is proposed:

  1. TIPs will be archived in a CVS repository.

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

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

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

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

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

  7. 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 [4]. 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.

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

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

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

  5. 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 [5] 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 at cs dot man dot ac dot uk>

Author replies to comments

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

Copyright

This document has been placed in the public domain.


Powered by Tcl[Index] [History] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]

TIP AutoGenerator - written by Donal K. Fellows