Updated 2013-05-31 19:34:33 by AK ▲

Information regarding how and where to provide feedback about Tcllib, and/or how and where to contribute code as well.

We want this to be a community-driven library, so we encourage submissions to this library. If you have written a function or set of functions that you find you use frequently, send the code in! Ultimately, we want community members to be responsible for modules in tcllib, having CVS write access directly to specific modules in the tree. Please do not feel that you must have a "complete" module in order to contribute -- individual functions are welcome as well.

Also, if you are using tcl code that was written by someone else, please contact that developer to help them contribute it to the library. The library should only include members' code with their cooperation, agreement, and support.

Important pages for Tcllib are

We have one mailing list for the discussion of Tcllib development. See http://lists.sourceforge.net/lists/listinfo/tcllib-devel for more information.

A second mailing list is http://lists.sourceforge.net/lists/listinfo/tcllib-bugs . It allows anyone to receive the notifications SourceForge sends out when bugs, feature requests, etc. are entered or changed, and when commits are made to the Tcllib CVS or related projects. Note that this list is not for the posting of bugs. For that we have the trackers mentioned above.

In order to encourage growth and use of tcllib, there are some ground rules that modules added to tcllib must follow:

  • the module must be Tcl only: no C extensions. This minimizes the barrier to use -- not everybody has the means or desire to compile extensions. We may someday start another meta-package of C extensions.
  • The module must use a namespace for its commands and variables
  • The module must be a proper Tcl package
  • The name of the package must be the same as the name of the namespace
  • The module must be released under the BSD license. If you cannot accept the terms of that license, please feel free to release your package independently of the tcllib. We feel that this license (the same one that Tcl itself is under) is the most conducive to use.
  • The module should have both documentation (in XML or man form) and a test suite. The module _must_ have either documentation or a test suite, and preferably both.
  • The module should adhere to the Tcl coding standards. See http://www.purl.org/tcl/home/doc/
  • The module should be of general use to a large number of programmers. We don't want tcllib to become the dumping ground for every tcl programmer's personal, highly-specialized functions.

We feel that these rules will help encourage contributions to the library as well as use of the library. Remember that almost everybody can use the BSD license, and not everybody is willing or able to compile extensions. Our ultimate goal is to encourage the use of Tcl by providing a broad, robust library of functionality.

Eric Melski Scriptics Corporation

LEG 2009-03-16: feels that he would rather like to use the "simplified BSD License" variant, found e.g. at [1], and credit himself as OWNER for a contributed package, rather than the "Regents of the University of California".

AK: Can you bring this up on the tcllib-devel mailing list ?

A follow up article by Jeff Hobbes said:

Several have asked some basic questions of tcllib, which I will address here.

  • Who maintains the module names?

The Tcl core group, with help from the community, will manage the toplevel package structure. This will prevent unlimited proliferation of names and confusing structure. We will also rely on a source like NICS:
    http://pitch.nist.gov/cgi-bin/nics/cgibin/domain_list.cgi

to make sure that uniqueness is maintained amongst all packages (those in tcllib and external ones).

Names should follow some reasonable/logical structure. Expanded math functions under ::math (like setmin, setmax), extended string functions under ::textutil (like (un)tabify, wrap_lines), etc. We'd like to make the 1.0 release have a good set of logical packages (namespaces).

  • How can software be submitted?

Modules (packages) within tcllib will be assigned maintainers (1+). Each maintainer will have CVS write access to that module. We would expect maintainers to follow all the basic style and quality standards for the tcllib, or risk losing CVS write privileges (not something we'd do without warning or good reason). If you want to become a module maintainer, you would just make the request to the Tcl Core Team.

  • What software can be submitted?

tcllib can be populated with any Tcl-only packages that adhere to the tcllib standards (built as package, all in one namespace). We don't want to include C packages, following basic KISS principles. Included packages may contain reqs for C-based extensions, but they must have a Tcl-only fallback. Also, any submitted software should be under BSD, so people know that they can pick this up and use it just as they do the Tcl/Tk core now.

  • What is the release schedule?

We basically make checkpoint releases every year or as a certain amount of new stuff comes in. The version management is planned as follows:
   #   Major version bump: reserved for when new toplevel packages are added
   #   Minor version bump: reserved for when new subpackages are added or significant functionality (like changed API) is made to existing packages
   #   Patch version bump: bug fixes to existing packages

We could go to a S.M.m.p system, where the new significant digit "S" refers to Structure, to allow ourselves versions in which we restructure tcllib.

  • Will it become part of the core?

Likely starting with 8.5, the core will include a snapshot release of tcllib, where tcllib maintains its own version number and is installed as a sibling to tcl<M.m>. tcllib would continue to be released separately.

From Andreas Kupries, this msg was provided:

1) What are the rules, requirements, restrictions for adding code to the tcllib?

See (5) below. Also note that a patch of an existing module or a new module should contain not only the code, but extend the testsuite and documentation (manpages) too. Both of the latter will make acceptance easier as they allow to check the correctness of the code now and in the future.

2) Who decides what does, or does not, get included into tcllib?

Essentially the people who are registered as developers for the Tcllib SF project.

3) Does anything get added into the library that someone submits?

Yes. Recent changes were the acceptance of a patch [x] fixing a bug in pop3 and several new modules ("md5" [*], "csv", "matrix" (as part of "struct"), "report", "log" and "htmlparse").

[x] Well, the patch was accepted a long time but Scott had troubles with committing it. When he tried yesterday it worked and so this bug finally squashed too.

[*] Based upon Don Libes implementation of MD5, "md5pure", with changes by me (Trf soft dependency).

4) Can Tk-specific commands be added to the tcllib?

Modules that depend on Tk are placed in a sub project of tcllib: tklib

5) Can Expect/Tix/Snack/etc. specific commands, which depend on some outside extension but which themselves are only script based, be added?

The main rule/restriction which was set up at the beginning was that 'tcllib' is a script-only library which should work without any C-level extension. So the answer to the above is 'no'.

This however does not exclude the usage of extensions to make tcllib faster, if it does work without the extensions too, albeit slower.

Examples of this are the "mime" and "md5" modules. Both have a soft-dependency on the C-level extension "Trf". If "Trf" is present, "mime" and "md5" will use it in their implementations to make certain operations faster (base64 and md5 respectively). If it is not present, both modules will fallback to pure-tcl implementations.

In general I (AK) would advise the following:

  • Go through your set of utilities and see if they match one of the existing modules of tcllib. If yes, submit a patch containing the new code and extended testsuite, documentation.
  • If there is no match, create a new module in the style of the existing modules (see, for example, md5). Submit either a patch or an archive containing the new files.

tclguy has written, "From http://tcllib.sf.net/ go to the patch manager and post your code. You might want to examine the tcllib distro first, to see if it already fits well into an existing module, or whether one should be created for it."

Recently someone on the Tcllib mailing list (sponsered at SourceForge) asked What would one have to do to be added as a developer to Tcllib?. The answer by AK was One of the project administrators (like me) needs the name of your sourceforge user account to be able to add you to the list of developers for the project.

Other things mentioned in the recent thread were:

  • extending test cases when one fixes a bug
  • creating test suites if none exist
  • dropping a note to the tcllib-developers mailing list if any major features or changes are planned for a module, letting people know and making certain the direction being taken makes sense,
  • writing doctools documentation if none exists
  • follow the Tcl style Guide when writing or modifying code
  • don't add new features without adding new doc
  • bump revision numbers when changing files
  • on questions of design, or naming, ask the developers mailing list
  • be certain to specify the required level of Tcl using package require

TODO for this page ...

  1. ... list of suggestions for inclusion in tcllib? - separate page ...
  2. ... developer information ... internal structure, helper tools ... - maybe referenced from the rules ?
  3. ... other types of help ... (wiki helper, doc writer, tester, ...)

Category Tcllib