# TIP 2: TIP Guidelines
Author: Andreas Kupries <[email protected]>
Author: Donal K. Fellows <[email protected]>
Author: Don Porter <[email protected]>
Author: Mo DeJong <[email protected]>
Author: Larry W. Virden <[email protected]>
Author: Kevin Kenny <[email protected]>
State: Draft
Type: Process
Vote: Pending
Created: 12-Sep-2000
Post-History:
-----
# Abstract
This document describes and defines the editorial process a TCT
document \(TIP\) has to go through before accepted as official.
# What is a TIP?
TIP stands for Tcl Improvement Proposal. A TIP is a design document
providing information to the Tcl community, or describing a new
feature for Tcl. The TIP should provide a concise technical
specification of the feature and a rationale for the feature.
We intend TIPs to be the primary mechanisms for proposing new
features, for collecting community input on an issue, and for
documenting the design decisions that have gone into Tcl. The TIP
author is responsible for building consensus within the community and
documenting dissenting opinions.
Because the TIPs are maintained as text files under revision control,
their history is the historical record of the feature proposal. This
historical record is available by the normal \(CVS?\) commands for
retrieving older revisions. For those without direct access to the
CVS tree, you can browse the current and past TIP revisions
<http://www.cs.man.ac.uk/fellowsd-bin/TIP/> .
Further details on the arguments behind the evolution of the TIP
concept and formatting can be found in the archive of the _tclcore_
mailing list
<http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/tcl-core> .
# Kinds of TIPs
There are three kinds of TIPs. A project TIP describes a new \(or
significantly updated\) feature or implementation for Tcl. An
informative TIP describes a Tcl design issue, or provides general
guidelines or information to the Tcl community, but does not propose a
new feature. A process TIP is like an informative TIP but the
provided guidelines are mandatory in a certain context \(as specified
in the TIP itself\).
Voting by the TCT as per the charter \(see [[0]](0.md)\) is required to make a
project or process TIP official.
# TIP Workflow
The TIP editor, Donal K. Fellows <[email protected]> _pro
tem_, is responsible for assigning numbers to each TIP and managing its
status on behalf of authors.
Everyone in the community can submit a TIP to the TIP editor. It should
contain at least a proposed title and a rough, but fleshed out, draft of the
TIP. It _must_ include a copyright statement that permits the normal
business of the TIP process as described here.
If the TIP editor approves, he will assign the TIP a number, label it as
either project, process or informational, give it status _Draft_, and create
and check-in the initial draft of the TIP. The TIP editor will not
unreasonably deny a TIP. Reasons for denying TIP status include gross
malformatting, inappropriate copyright, duplication of effort, being
technically unsound, or not in keeping with the Tcl philosophy; the TCT and
after that John Ousterhout <[email protected]> is the final arbitrator of the
latter, as defined in the charter \([[0]](0.md)\).
Discussion concerning a TIP should initially be kept out of the
tclcore and tct mailing lists. Instead, comments should be sent to,
and collected by, the TIP author, who has the responsibility to
incorporate these comments into the document.
_Note:_ It has been proposed to create a new mailing list for each
TIP to handle its discussion. Rejection and finalization of the TIP
closes the mailing list, but not the archive. Together with the CVS
history a complete record of the development of a TIP will be
available.
The authors of the TIP are responsible for writing the TIP and
marshaling community support for it. The structure of a TIP is
described in detail in [[3]](3.md).
A project TIP consists in principle of two parts, a design document and a
reference implementation. The TIP will not normally be reviewed and accepted
before a reference implementation is begun so that the amount of time between
acceptance and a final implementation can be minimized. The implementation can
be given in the form of code, patch, or URL to same, and _must_ be applied
to the Tcl/Tk core before it can be considered _Final_; while small
reference implementations may be placed inside the TIP itself, large reference
implementations should be held externally and linked to by reference
\(typically a URL\). Authors are encouraged to use the SourceForge Patch
trackers for this purpose.
Process and Informational TIPs do not need an implementation.
TIP authors are responsible for collecting community feedback on a TIP
before submitting it for review \(the creation of a TIP is a part of
that review process.\) However, wherever possible, long open-ended
discussions on public mailing lists should be avoided. A better
strategy is to encourage public feedback directly to the TIP author,
who collects and integrates the comments back into the TIP.
Once the authors have completed a TIP, they must inform the Tcl Core
Team that it is ready for review. TIPs are reviewed by the Tcl Core
Team and \(for Project TIPs\) the maintainers for the relevant parts of
the core, who may accept or reject a TIP or send it back to the
author\(s\) for revision \(as detailed in [[0]](0.md).\) The acceptance or
rejection of a TIP will cause its state to be changed accordingly to
_Accepted_ or _Rejected_.
Once a TIP requiring a reference implementation has been accepted, the
reference implementation must be completed. When the reference implementation
is complete and accepted by the TCT \(who can reject it if they feel the
implementation would damage the rest of the core\) the status will be changed
to _Final_. This is usually done by the TIP Editor, as advised by the
responsible Tcl/Tk maintainer.
A TIP can also be assigned status _Deferred_. The TIP author or the
editor can assign the TIP this status when no progress is being made
on the TIP. Once a TIP is deferred, the TIP editor can re-assign it
to _Draft_ status.
A TIP can also be _Withdrawn_ by the author. Perhaps after all is
said and done, the author believes it was not a good idea. It is
still important to have a record of this fact. It is expected that
_Accepted_ TIPs will only be withdrawn very rarely, and _Final_
TIPs only under exceptional circumstances.
TIP workflow is as follows:
Some informative TIPs may also have a status of _Active_ if they are
never meant to be completed. For example: [[1]](1.md).
# What belongs in a successful TIP?
Each TIP should have the following parts:
1. _Title_ - a short, descriptive title.
2. _Author_\(s\) - names and contact info \(email addresses\) for each
author.
3. _Abstract_ - a short \(typically <200 word\) description of the
technical issue being addressed.
4. _Copyright_/public domain - Each TIP must either be explicitly
labelled in the public domain \(the preferred 'license'\) or the
Open Publication License <http://www.opencontent.org/openpub/> .
It is recommended that this be done by making the last section of
the document be a copyright heading, with the body describing what
copyright \(if any\) the document is released under.
5. _Specification_ - Project TIPs should have a technical
specification that should describe the syntax and semantics of any
new language feature. The specification should be detailed enough
to allow \(competing\) interoperable implementations for any of the
current Tcl platforms.
6. _Rationale_ - The rationale fleshes out the specification by
describing what motivated the design and why particular design
decisions were made. It should describe alternate designs that
were considered and related work, _e.g._ how the feature is
supported in other languages.
> The rationale should provide evidence of consensus within the
community and discuss important objections or concerns raised
during discussion.
7. _Reference Implementation_ - The reference implementation must
be completed before any TIP requiring such is given status
_Final_, but it need not be completed before the TIP is
accepted. It is better to finish the specification and rationale
first and reach consensus on it before writing code.
> The final implementation must include test code and documentation
appropriate for either the Tcl language reference or the standard
library reference.
# TIP Style
TIPs are written in plain ASCII text with an RFC822-like header and
embedded sequences suitable for Wiki-like processing as indicated in
[[3]](3.md).
There are Tcl scripts that convert the TIP into HTML for viewing on
the web. Scripts for producing other formats are available too, for
example LaTeX and plain ASCII.
# Sample Project TIP
\(With thanks to William H. Duquette <[email protected]>
for suggesting this.\) Note that the TIP Editor is responsible for
allocating TIP numbers, so you can leave that unfilled.
TIP: ???
Title: The TIP Title as Plain Text
Version: $Revision: 1.38 $
Author: Author Name <[email protected]>
State: Draft
Type: Project
Tcl-Version: 8.4
Vote: Pending
Created: 31-Feb-1999
Post-History:
~ Abstract
This is an example of how to write a simple project TIP. This is the
abstract which should consist of a single paragraph of under 200
words. If you need more than this, you should stop and think about
writing a real abstract, not a whole section! :^)
~ Some Sections
Yada yada yada. Look at the sources to the various TIPs for tricks
on how to do various things. ''Note that for complete legal safety,
you must specify what copyright is used.'' We prefer public domain,
as it allows others (notably the TIP editor(s)) to maintain the TIP
as necessary without having to seek permission.
I also prefer to make sure TIP and section titles are capitalized
according to the usual rules of English.
~ Copyright
This document has been placed in the public domain.
A more complex example is [[7]](7.md) by Kevin Kenny <[email protected]> \(the
source is at <http://www.cs.man.ac.uk/fellowsd-bin/TIP/7.tip\)> and which
includes demonstrations of how to use advanced features like figures
and verbatim text. His is a very high quality TIP though, and it has
been though several revisions; don't feel too put off if your first
attempt isn't quite as good...
# Patches
For preference, patches to Tcl should be stored separately on another
website or submitted as a separate file. This is because \(quite
rightly\) the news:comp.lang.tcl.announce moderator does not allow
patches to be posted on that newsgroup. If you want a patch to be
incorporated into the archive, please contact the TIP Editor.
----
# Comments
> From Don Porter < [email protected] > :
> 1. It is confusing that "project" TIPs defined here do not
correspond to "projects" defined in [[0]](0.md).
> 2. The TIP Workflow section should mention the web-based
drafting service [[13]](13.md) as another way for members of the
community to add their comments to a draft TIP.
> 3. The TIP Workflow section calls for TCT acceptance of a
project TIP implementation to move it from state Accepted
to state Final. This conflicts with [[0]](0.md) which delegates that
acceptance task to maintainers.
> 4. It is not clear how the TIP workflow state diagram applies
to non-project TIPs. Non-project TIPs do not have an
implementation. Do they move straight from state Draft to
state Final when they receive TCT approval? Or do they
just stay in state Accepted forever with no need to move to
state Final?
> 5. It should be noted in the TIP Workflow section that according
to [[0]](0.md) a project TIP cannot be approved \(and therefore should
not be sponsored\) until the TIP names a committed implementor.
> 6. The Patches section indicates that patches in the TIP are
incompatible with posting to comp.lang.tcl.announce, so
earlier sections of this TIP should not indicate that including
patches in the TIP is an acceptable practice.
> 7. Should process TIPs be reserved for those proposals that
revise [[0]](0.md) and require 2/3 support of the entire TCT?
From Mo DeJong:
It seems like we have a documentation problem with
respect to how a TIP becomes "un-rejected".
The text says:
> ... may accept or reject a TIP or send it back to the author\(s\)
for revision"
But the state transition diagram shows no way to go from
_Rejected_ to _Draft_. What becomes of a TIP after it
is put up for a vote? If it is rejected, should the
author create a new TIP number or can they rewrite
the original TIP?
----
_Larry W. Virden writes:_ I would really find it useful
if upon submission of a TIP, a web page, perhaps on
the Tcl'ers Wiki or elsewhere, would be referenced in
the TIP itself. This web page would contain a summary
of the discussion to date, perhaps containing urls
to relevant postings within the tct archives, etc.
This page could be used by those looking at the
archive to quickly determine the state of the discussion,
as well as the reasons for the final disposition of the
TIP.
_Donal Fellows responds:_ Feel free to establish such things. But I've
definitely not got time to maintain them, and especially haven't got time to
go back through the archives to make the resource complete for those TIPs that
have already been voted upon.
----
# Copyright
This document has been placed in the public domain.