# TIP 2: TIP Guidelines
	Author:         Andreas Kupries <a.kupries@westend.com>
	Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
	Author:         Don Porter <dgp@users.sourceforge.net>
	Author:         Mo DeJong <no@spam.com>
	Author:         Larry W. Virden <lvirden@yahoo.com>
	Author:         Kevin Kenny <kennykb@acm.org>
	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 <donal.k.fellows@manchester.ac.uk> _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 <ouster@pacbell.net> 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:

![TIP Workflow](../assets/2workflow.gif)

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 <William.H.Duquette@jpl.nasa.gov>
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 <author@somewhere.com>
	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 <kennykb@acm.org> \(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  < dgp@users.sourceforge.net > :

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

