Author: Donal K. Fellows <[email protected]>
State: Draft
Type: Informative
Vote: Pending
Created: 07-Jul-2001
Post-History:
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 [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 [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 news:comp.lang.tcl, news:comp.lang.tcl.annouce and the tcl-core mailing list (though with some TIPs it is obvious that wider dissemination is less useful.) It is a good idea to send a copy to the TIP author as well, as this lets them know not only that the TIP has been accepted but also what it looks like and that it has been distributed to the wider community. The postnews.tcl script that comes with the TIP renderer distribution is designed to do all this with a minimum of fuss. A quick "Thank You" note is also courteous.
When a TIP has been accepted by the TCT in a TYANNOTT vote, put a note into the log to record what the vote was. It is best to do this as part of the log message for when you change the Vote: and Status: headers...
If a TIP does not state whether it is an alteration to Tcl or Tk in either its title or its abstract, it is a good idea to add a Keywords: header (or a keyword in an existing such header) which includes that information.
Don't forget to use both bold and italic text when formatting strings that represent command syntaxes. It makes them much clearer!
I need to write something here about the production of PS and PDF versions of the whole TIP archive, but that side of the code is not yet finished and released.
Notes
TIPs do not need to be tightly focussed. Making them so does make them easier to evaluate, but it might also remove the real rationale behind the changes. Instead, it is best that they form a coherent logical entity, since I believe that it is that which makes for a good TIP.
The title, section headings and list item headings must be plain text. This is because there are output formats which are very picky about what is allowed in those sorts of places (PDF bookmarks have especially strict restrictions) and plain text has the virtue of being accepted pretty much everywhere.
Copyright
This document is placed in the public domain.