TIP: 43
Title: How to be a TIP Editor
Version: $Revision: 1.4 $
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.