TIP 16: Tcl Functional Areas for Maintainer Assignments

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Don Porter <dgp@users.sourceforge.net>
Author:         Daniel Steffen <das@users.sourceforge.net>
State:          Accepted
Type:           Process
Vote:           Done
Created:        21-Nov-2000
Post-History:   

Abstract

This document proposes a division of Tcl's source code into functional areas so that each area may be assigned to one or more maintainers.

Background

TCT procedures (see [0]) call for each maintainer to be responsible for a portion of Tcl's source code. Certain portions of Tcl's source code are naturally associated with certain other portions. (For example, the implementation of a command is intimately related to the documentation for that command.) Establishing a natural division of Tcl's source code into units needing maintainers is a useful preliminary effort toward a public call for volunteer maintainers.

See [24] for the mapping of these functional areas to maintainers.

Rationale

When someone reports a bug, or offers a patch, he will want to be able to determine what maintainers have oversight over his report. This implies that we seek a simple mapping from something he knows about his bug or patch to the set of maintainers.

For a patch, the submitter certainly knows what file(s) she is patching. For a bug report, the reporter is likely to know what command or C function he believes to be buggy. Fortunately, every C function or Tcl command (combined with the platform) can be associated with exactly one source code file, the file providing the definition of the C function, or the command procedure of the Tcl command. Thus, a mapping from source code file to maintainer is sufficient to complete the determination.

The source code file should not be the largest unit, however. Certain sets of files should each be gathered into a larger unit, all files in that unit with the same maintainer(s). Tcl's man pages already gather related routines and commands into one page of documentation. Using the modules implied by the man pages, and by the location of routines in particular source code files, a natural division of Tcl into minimal maintainer units follows in the Proposal section below.

It may be that some of these minimal units can be joined together into still larger related units. That is not necessary, though. We can just have the same maintainer(s) assigned to all the related minimal units.

Functional Areas

Tcl shall be divided into the following functional units, each to be assigned one or more maintainers:

Events

  1. Notifier - doc/CrtFileHdlr.3, doc/DoOneEvent.3, doc/Notifier.3, doc/Sleep.3, generic/tclNotify.c, macosx/tclMacOSXNotify.c, tests/notify.test, tests/unixNotfy.test, tests/winNotify.test, unix/tclUnixNotfy.c, unix/tclUnixEvent.c, win/tclWinNotify.c

  2. Event Loops - doc/bgerror.n, doc/update.n, doc/vwait.n, doc/BackgdErr.3, doc/Exit.3, generic/tclEvent.c, tests/event.test

  3. Timer Events - doc/after.n, doc/CrtTimerHdlr.3, doc/DoWhenIdle.3, generic/tclTimer.c, tests/timer.test

  4. Asynchronous Events - doc/Async.3, generic/tclAsync.c, tests/async.test

  5. Xt Based Notifier - unix/tclXtNotify.c, unix/tclXtTest.c

  6. Time Measurement - compat/gettod.c, compat/strftime.c, doc/clock.n, generic/tclClock.c, generic/tclGetDate.y, library/tzdata/*, tests/clock.test, tests/winTime.test, tools/loadICU.tcl, tools/makeTestCases.tcl, tools/tclZIC.tcl, unix/tclUnixTime.c, win/tclWinTime.c

Variables

  1. Variable Commands and Interfaces - doc/append.n, doc/array.n, doc/global.n, doc/lappend.n, doc/lset.n, doc/set.n, doc/unset.n, doc/upvar.n, doc/variable.n, doc/SetVar.3, doc/UpVar.3, generic/tclVar.c, tests/append.test, tests/lset.test, tests/set.test, tests/set-old.test, tests/upvar.test, tests/var.test

  2. Environment Variables - doc/Environment.3, generic/tclEnv.c, tests/env.test

  3. Linked C Variables - doc/LinkVar.3, generic/tclLink.c, tests/link.test

Objects

  1. Object System and Fundamental Object Types - doc/Backslash.3, doc/BoolObj.3, doc/Concat.3, doc/DoubleObj.3, doc/DString.3, doc/Encoding.3, doc/FindExec.3, doc/Hash.3, doc/IntObj.3, doc/Object.3, doc/ObjectType.3, doc/PrintDbl.3, doc/SplitList.3, doc/StringObj.3, doc/StrMatch.3, generic/tclEncoding.c, generic/tclHash.c, generic/tclObj.c, generic/tclStringObj.c, generic/tclUtil.c, library/encoding/*.enc, tools/encoding/*, tests/dstring.test, tests/encoding.test, tests/stringObj.test, tests/obj.test, tests/util.test

  2. Conversions From String - doc/GetInt.3, generic/tclGet.c, tests/get.test

  3. bytearray Object Type - doc/binary.n, doc/ByteArrObj.3, generic/tclBinary.c, tests/binary.test

  4. index Object Type - doc/GetIndex.3, doc/WrongNumArgs.3, generic/tclIndexObj.c, tests/indexObj.test

  5. list Object Type - doc/ListObj.3, generic/tclListObj.c, tests/listObj.test

  6. dict Object Type - doc/DictObj.3, doc/dict.n, generic/tclDictObj.c, tests/dict.test

Fundamental Built-in Commands

  1. A - H - doc/break.n, doc/case.n, doc/catch.n, doc/cd.n, doc/concat.n, doc/continue.n, doc/encoding.n, doc/error.n, doc/eval.n, doc/exit.n, doc/expr.n, doc/file.n, doc/for.n, doc/foreach.n, doc/format.n, generic/tclCmdAH.c, tests/cmdAH.test tests/case.test, tests/concat.test, tests/error.test, tests/eval.test, tests/foreach.test, tests/format.test, tests/for-old.test

  2. I - L - doc/if.n, doc/incr.n, doc/info.n, doc/join.n, doc/lindex.n, doc/linsert.n, doc/list.n, doc/llength.n, doc/lrange.n, doc/lreplace.n, doc/lsearch.n, doc/lsort.n, generic/tclCmdIL.c, tests/cmdIL.test, tests/if-old.test, tests/incr-old.test, tests/info.test, tests/join.test, tests/lindex.test, tests/linsert.test, tests/list.test, tests/llength.test, tests/lrange.test, tests/lreplace.test, tests/lsearch.test

  3. M - Z - doc/pwd.n, doc/regexp.n, doc/regsub.n, doc/rename.n, doc/return.n, doc/split.n, doc/string.n, doc/subst.n, doc/switch.n, doc/throw.n, doc/time.n, doc/try.n, doc/while.n, generic/tclCmdMZ.c, tests/cmdMZ.test tests/pwd.test, tests/rename.test, tests/split.test, tests/string.test, tests/subst.test, tests/switch.test, tests/while-old.test

  4. [history] - doc/history.n, doc/RecEvalObj.3, doc/RecordEval.3, generic/tclHistory.c, library/history.tcl, tests/history.test

  5. [interp] - doc/interp.n, doc/CrtSlave.3, doc/Limit.3, generic/tclInterp.c, tests/interp.test

  6. [namespace] - doc/Namespace.3, doc/namespace.n, generic/tclEnsemble.c, generic/tclNamesp.c, generic/tclResolve.c, tests/namespace.test, tests/namespace-old.test

  7. [proc] - doc/proc.n, doc/uplevel.n, generic/tclProc.c, generic/tclTestProcBodyObj.c, tests/proc.test, tests/proc-old.test, tests/uplevel.test

  8. [scan] - doc/scan.n, generic/tclScan.c, tests/scan.test

Channels

  1. Channel Commands - doc/close.n, doc/eof.n, doc/exec.n, doc/fblocked.n, doc/fconfigure.n, doc/fcopy.n, doc/flush.n, doc/gets.n, doc/open.n, doc/puts.n, doc/read.n, doc/seek.n, doc/socket.n, doc/tell.n, generic/tclIOCmd.c, tests/exec.test, tests/ioCmd.test, tests/remote.tcl, tests/socket.test

  2. Channel System - doc/chan.n, doc/fileevent.n, doc/ChnlStack.3, doc/CrtChnlHdlr.3, doc/CrtCloseHdlr.3, doc/CrtChannel.3, doc/DetachPids.3, doc/GetStdChan.3, doc/OpenFileChnl.3, doc/StdChannels.3 generic/tclIO.c, generic/tclIO.h, generic/tclPipe.c, tests/chan.test, tests/chanio.test, tests/io.test

  3. Channel Transformations - generic/tclIOGT.c, generic/tclIORTrans.c, tests/iogt.test, tests/ioTrans.test

  4. Built-in Channel Types - compat/waitpid.c, doc/GetHostName.3, doc/GetOpnFl.3, doc/OpenTcp.3, doc/pid.n, generic/tclIOSock.c, generic/tclIORChan.c, tests/pid.test, tests/winConsole.test, tests/winPipe.test, unix/tclUnixChan.c, unix/tclUnixPipe.c, unix/tclUnixSock.c, win/cat.c, win/stub16.c, win/tclWinChan.c, win/tclWinConsole.c, win/tclWinPipe.c, win/tclWinSerial.c, win/tclWinSock.c

Packages

  1. dde Package - doc/dde.n, library/dde/pkgIndex.tcl, tests/winDde.test win/tclWinDde.c

  2. http Package - doc/http.n, library/http1.0/http.tcl, library/http1.0/pkgIndex.tcl, library/http/http.tcl, library/http/pkgIndex.tcl, tests/http.test, tests/httpd, tests/httpold.test

  3. msgcat Package - doc/msgcat.n, library/msgcat/msgcat.tcl, library/msgcat/pkgIndex.tcl, tests/msgcat.test

  4. opt Package - library/opt/optparse.tcl, library/opt/pkgIndex.tcl, tests/opt.test

  5. registry Package - doc/registry.n, library/reg/pkgIndex.tcl, win/tclWinReg.c, tests/registry.test

  6. Safe Base - doc/safe.n, library/safe.tcl, tests/safe.test

  7. tcltest Package - doc/tcltest.tcl, library/tcltest/tcltest.tcl, library/tcltest/pkgIndex.tcl, tests/tcltest.test

  8. TclOO Package (see [257]) - doc/Class.3, doc/Method.3, doc/class.n, doc/copy.n, doc/define.n, doc/my.n, doc/next.n, doc/object.n, doc/self.n, generic/tclOO.c, generic/tclOO.decls, generic/tclOO.h, generic/tclOOBasic.c, generic/tclOOCall.c, generic/tclOODefineCmds.c, generic/tclOOInfo.c, generic/tclOOInt.h, generic/tclOOMethod.c, tests/oo.test

File System

  1. Pathname Management - doc/filename.n, doc/glob.n, doc/FileSystem.3, doc/SplitPath.3, doc/Translate.3, generic/tclFileName.c, tests/fileName.test, tests/unixFile.test, tests/winFile.test, unix/tclUnixFile.c, win/tclWinFile.c

  2. File System Access - doc/Access.3, doc/GetCwd.3, doc/SetErrno.3, doc/Signal.3, generic/tclFCmd.c, generic/tclIOUtil.c, generic/tclPathObj.c, generic/tclPosixStr.c, macosx/tclMacOSXFCmd.c, tests/fCmd.test, tests/ioUtil.test, tests/unixFCmd.test, tests/winFCmd.test, unix/tclUnixFCmd.c, win/tclWinError.c, win/tclWinFCmd.c

Initialization, Script Library, and Autoloader

  1. doc/library.n, doc/tclvars.n, doc/unknown.n, doc/Init.3, doc/SourceRCFile.3, generic/tclInitScript.h, library/auto.tcl, library/init.tcl, library/parray.tcl, library/word.tcl, macosx/tclMacOSXBundle.c, tests/autoMkindex.tcl, tests/autoMkindex.test, tests/init.test, tests/platform.test, tests/security.test, tests/unixInit.test, tests/unknown.test, unix/tclUnixInit.c, win/tclWinInit.c

Package Support

  1. Package Management - doc/InitStubs.3, doc/package.n, doc/packagens.n, doc/pkgMkIndex.n, doc/PkgRequire.3, doc/tm.n, generic/tclPkg.c, generic/tclStubLib.c, library/package.tcl, library/tm.tcl, tests/package.test, tests/pkg.test, tests/pkgMkIndex.test, tests/pkg/*.tcl, tests/tm.test

  2. Dynamic Loading - compat/dlfcn.h, doc/load.n, doc/StaticPkg.3, generic/tclLoad.c, generic/tclLoadNone.c, library/ldAout.tcl, tests/load.test, unix/dltest/*, unix/tclLoad*.c, win/tclWinLoad.c

Memory Management

  1. Allocation - doc/memory.n, doc/Alloc.3, doc/TCL_MEM_DEBUG.3, doc/DumpActiveMemory.3, generic/tclAlloc.c, generic/tclCkalloc.c, generic/tclThreadAlloc.c

  2. Preservation - doc/Preserve.3, generic/tclPreserve.c

Regular Expressions

  1. doc/re_syntax.n, doc/RegExp.3, generic/regc_color.c, generic/regc_cvec.c, generic/regc_lex.c, generic/regc_locale.c, generic/regc_nfa.c, generic/regcomp.c, generic/regcustom.h, generic/rege_dfa.c, generic/regerror.c, generic/regerrs.h, generic/regex.h, generic/regexec.c, generic/regfree.c, generic/regfronts.c, generic/regguts.h, generic/tclRegexp.c, generic/tclRegexp.h, tests/reg.test, tests/regexp.test, tools/uniClass.tcl

UTF-8 String Management

  1. doc/ToUpper.3, doc/UniCharIsAlpha.3, doc/Utf.3, generic/tclUtf.c, tools/uniParse.tcl, tests/utf.test, win/tclWin32Dll.c

Fundamentals

  1. Parsing and Evaluation - doc/AddErrInfo.3, doc/AllowExc.3, doc/AssocData.3, doc/CallDel.3, doc/CmdCmplt.3, doc/CrtCommand.3, doc/CrtObjCmd.3, doc/CrtInterp.3, doc/CrtMathFnc.3, doc/Eval.3, doc/ExprLong.3, doc/ExprLongObj.3, doc/GetVersion.3, doc/Interp.3, doc/NRE.3, doc/ParseCmd.3, doc/SaveResult.3, doc/SetRecLimit.3, doc/SetResult.3, doc/Tcl.n, generic/tclBasic.c, generic/tclParse.c, generic/tclParseExpr.c, generic/tclResult.c, tests/assocd.test, tests/basic.test, tests/cmdInfo.test, tests/dcall.test, tests/expr-old.test, tests/parse.test, tests/parseExpr.test, tests/parseOld.test, tests/result.test, tests/stack.test

  2. Traces - doc/TraceVar.3, doc/TraceCmd.3, doc/trace.n, doc/CrtTrace.3, generic/tclTrace.c, tests/trace.test

  3. Bytecode Compiler - compat/float.h, generic/tclAssembly.c, generic/tclCompCmds.c, generic/tclCompCmdsSZ.c, generic/tclCompExpr.c, generic/tclCompile.c, generic/tclCompile.h, generic/tclExecute.c, generic/tclLiteral.c, generic/tclMathOp.c, generic/tclOptimize.c, tests/appendComp.test, tests/compExpr-old.test, tests/compExpr.test, tests/compile.test, tests/execute.test, tests/expr.test, tests/for.test, tests/if.test, tests/incr.test, tests/lsetComp.test, tests/regexpComp.test, tests/stringComp.test, tests/while.test

  4. Number Handling (see [237]) - generic/tclStrToD.c, generic/tclTomMath.h, generic/tclTomMathInterface.c, generic/tommath.h, libtommath/*

Threads

  1. doc/Thread.3, generic/tclThread.c, generic/tclThreadJoin.c, generic/tclThreadStorage.c, generic/tclThreadTest.c, tests/thread.test, unix/tclUnixThrd.c, unix/tclUnixThrd.h, win/tclWinThrd.c, win/tclWinThrd.h

Embedding Support

  1. doc/AppInit.3, doc/Tcl_Main.3, doc/Panic.3, doc/tclsh.1, generic/tclMain.c, generic/tclPanic.c, tests/main.test, unix/tclAppInit.c, win/tclAppInit.c

Release Engineering

  1. Release Notes - README, changes, license.terms, */license.terms, compat/README, generic/README, macosx/README, tests/README, tests/pkg/license.terms, tools/README, unix/README, win/README

  2. Portability Support - compat/dirent.h, compat/dirent2.h, compat/limits.h, compat/fixstrtod.c, compat/memcmp.c, compat/opendir.c, compat/stdlib.h, compat/string.h, compat/strncasecmp.c, compat/strstr.c, compat/strtod.c, compat/strtol.c, compat/strtoul.c, compat/tclErrno.h, compat/tmpnam.c, compat/unistd.h, generic/tclMath.h, generic/tclPort.h, unix/tclMtherr.c, unix/tclUnixPort.h, unix/tclUnixCompat.c, win/tclWinMtherr.c, win/tclWinPort.h

  3. Configuration and Build Tools - djgpp/Makefile, macosx/Makefile, macosx/Tcl.pbproj/project.pbxproj, tests/all.tcl, tools/configure.in, tools/eolFix.tcl, tools/genStubs.tcl, tools/index.tcl, tools/Makefile.in, tools/man2help.tcl, tools/man2help2.tcl, tools/man2tcl.c, tools/mkdepend.tcl, tools/tcl.hpj.in, tools/tcl.wse.in, tools/tclSplash.bmp, tools/tcltk-man2html.tcl, tools/white.bmp, unix/Makefile.in, unix/aclocal.m4, unix/configure.in, unix/install-sh, unix/ldAix, unix/mkLinks, unix/mkLinks.tcl, unix/tcl.m4, unix/tcl.spec, unix/tclConfig.sh.in, win/Makefile.in, win/aclocal.m4, win/buildall.vc.bat, win/coffbase.txt, win/configure.in, win/makefile.vc, win/makefile.bc, win/mkd.bat, win/rmd.bat, win/rules.vc, win/tcl.dsp, win/tcl.dsw, win/tcl.hpj.in, win/tcl.m4, win/tcl.rc, win/tclConfig.sh.in, win/tclsh.ico, win/tclsh.rc

  4. Configuration Reporting (see [59]) - doc/RegConfig.3, generic/tclConfig.c, generic/tclPkgConfig.c, tests/config.test, win/tclWinPkgConfig.c

  5. Other Tools - tools/checkLibraryDoc.tcl, tools/findBadExternals.tcl, tools/genWinImage.tcl, tools/man2html.tcl, tools/man2html1.tcl, tools/man2html2.tcl, tools/regexpTestLib.tcl

    1. LibTomMath - libtommath/*
    2. zlib (see [234]) - doc/zlib.n, doc/TclZlib.3, generic/tclZlib.c, tests/zlib.c

Shared Files

The following files are shared by all of Tcl. Any maintainer may modify them as necessary to complete changes they are making to their portion of Tcl. Some of the following files define Tcl's API and should be changed only in accordance with TCT approval.

  • ChangeLog, ChangeLog.*, doc/man.macros, generic/tcl.decls, generic/tcl.h, generic/tclInt.decls, generic/tclInt.h, generic/tclTest.c, generic/tclTestObj.c, tests/misc.test, unix/tclUnixTest.c, win/tclWinInt.h, win/tclWinTest.c

Generated Files

The following files are generated, so they don't need maintainers.

  • generic/tclDate.c, generic/tclUniData.c, generic/tclDecls.h, generic/tclIntDecls.h, generic/tclIntPlatDecls.h, generic/tclOODecls.h, generic/tclOOIntDecls.h, generic/tclOOStubInit.c, generic/tclOOStubLib.c, generic/tclPlatDecls.h, generic/tclStubInit.c, generic/tommath.h, library/tclIndex, unix/configure, win/configure

Copyright

This document has been placed in the public domain.

History