TIP #43 Version 1.1: How to be a TIP Editor

This is not necessarily the current version of this TIP.

Abstract

This TIP describes some of the rules and guidelines that the TIP Editor uses when accepting TIPs for the first time.

Rules

There are some things that are hard rules, which should be obeyed even if it means having to postpone acceptance of the TIP or rewrite it yourself.

• Every TIP must be relevant to Tcl and/or Tk.

  It's probably better to suggest that changes that affect just a single extension should be dealt with through the processes for feature requests for that extension, but where they are about providing some kind common interface across a whole group of extensions, it is fair to think of using a TIP as well. I'd reckon that's up to the discretion of the editor, but no TIP should be rejected by the editor out of hand, and never without a proper written explanation.

  Of course, ultimately whether a TIP is relevant to Tcl and/or Tk is up to the whole Tcl Core Team (as described in TIP #0) so you should try to ensure that their policy on TIP-suitability is what you are enforcing.

• Every TIP must be in the TIP format (see TIP #3 for details.)

  This is important because it allows the TIP rendering engine to handle all the formatting and indexing automatically for you. Note that it is very picky about the format of the header, and not that choosy about the format of the content (though it is not a good idea to have a sub-item of a list without a previous main item.) Get it wrong, and the TIP archive engine will fail in all sorts of "interesting" ways. Take particular note of the format of the Created: line, as it surprises many people in just how exact it must be.

• Every author must be associated with a real email address.

  You should fill this in yourself if it is not already supplied and spam-protected addresses are not acceptable, since they tend to frustrate the main purpose of TIPs which is to foster collaboration on things to improve Tcl and Tk. Proper email addresses help this by always allowing people to contact the author of the TIP to give suggestions to improve the TIP or to resolve issues they have with it.

• Every TIP must have an Abstract.

  Not everyone has the desire, or the time, to read each TIP. Providing an abstract allows people to determine whether the TIP is relevant to what they are looking for at the moment. Searches on the TIP archive also always search the abstract.

  Abstracts should be formed of the section title whose text is precisely "Abstract" and then a single normal paragraph of no more than around 200 words; if it is longer than that then it is no longer a summary or abstract but a genuine major part of the document body. While authors should write their own abstracts, it is reasonable for the editor to add one, particularly if the author's native language is not English.

• Every TIP must have a Copyright declaration.

  World-wide copyright laws are funny things, and I'm not sure that it is safe to assume that the submission of the TIP constitutes permission for all the things that might be done with it in the future. Work around this by getting every author to clarify the copyright position at time of submission by explicitly saying that the document is placed in the public domain. (The way that TIPs are kept under CVS should assuage most concerns relating to misrepresentation through inappropriate modifications, and it is a definite aim that TIPs should be distributed as widely as possible to encourage a wide dissemination of the ideas contained.)

Guidelines

• TIPs should be written in English (unless there are very good reasons otherwise) since that is the language most widely understood in the Tcl/Tk community.

• TIP should be written so as to be readable! This requirement is not strict, but it will make it much easier for the TCT to evaluate...

• The Abstract should be written in a third-person voice, and definitely in English. It isn't so important for the rest of the TIP, but the abstract will be seen quite a bit more widely and without as much context. It also fits in with the style of the existing abstracts.

• The section headings and title should be capitalised according to the rules for such things in English. It looks neater that way.

• Spell check before checking in. No sense in having glaring errors in the initial version! (I do not enforce the use of either US or UK spellings; that is rightfully the domain of the TIP author who might be based anywhere in the world.) Be especially careful with the checking of the spellings of the names of file names, C identifiers or Tcl commands/variables/etc.

• C identifiers and Tcl commands/variables/etc. should normally be emphasized, as should file names. This should be moderated by good sense though; the aim of such emphasis is to indicate that it is a reference to an entity in the code domain as opposed to the domain of the English language.

• TIP numbers should be allocated by the TIP editor in sequence of the order they are checked into the CVS archive. Make sure that the filename (num.tip) matches up with the TIP: num header or bizarre things may happen.

• Where someone submits a TIP proposing a new Tk widget, invite them to supply an image (or two) of how the widget will look in operation. These images will need to be checked in by hand, and will not be editable. Images should be checked in in both a raster form (GIF, JPEG or PNG) and as Encapsulated PostScript (EPS) - make sure that you set the binary flag on the file when you do this. Where someone produces a diagram with a tool that can produce FIG files, it is nice if you can check that into CVS as well so that the diagram itself can be maintained if necessary.

  As a convention, name the images with the TIP number as the first part of the name. This makes it much easier to determine what TIP a particular image is associated with (and certainly beats grepping the whole set of TIPs!)

• Once a TIP is checked in, it should normally be published to