There are many ways to contribute to Tcl/Tk core development. You
don't have to be a C programmer, and you don't have to invest a lot of
time. The most important thing is that you want to help.
What Needs to Be Done
Write Documentation-
Although the existing documentation for the Tcl/Tk core is good and
fairly complete, there is always room for improvement. We need
documentation for Tcl/Tk commands, C API's, and "Tcl Internals" design
documents on topics such as the bytecode compiler and the Tcl parser.
If you notice an error in any documentation, report it as a bug and
submit a patch to correct the error!
Report Bugs-
If you find a bug in the Tcl/Tk core, report it! Before reporting a
bug, you should query the
bug database to
make sure the bug has not already been submitted. You can submit a bug
report here.
A good bug report includes the following information:
- Synopsis of the bug
- The synopsis is the human readable reference to a bug report;
humans don't attach much meaning to bug number. This synopsis should
be a short answer to the questions, "How does an end-user recognize
the bug? How does the defect manifest itself?"
- Setup information
- This should list how things were setup before the steps to
reproduce are followed. Version of the product, build environment,
operating system and version, and similar information should be included.
- Steps to reproduce the bug
- This should be a list of clear, complete, and concise steps to
reproduce the bug. There is a fine balance between too much
information, just the right amount of information, and too little
information. The goal is that there is enough information to
reproduce the bug 100% of the time, and no red herrings when trying to
resolve the bug.
- Expected result
- After following the steps to reproduce the bug, what was the
expected result? It is the failure to meet this expectation that
creates a bug report. However, the expectation may be wrong.
- Actual result
- If the expected result is correct, then whatever actually happens
is a bug. The expected result needs to be as clear, complete, and
concise as the steps to reproduce; it is the strongest lead to the
underlying defect. If the bug results in a core dump, say so; if
possible, include a core backtrace from the point of failure.
- Additional information
- Commonsense dictates that there may be additional information that
is relevant to the bug, but that doesn't fall into the neat categories
listed above. Include it as a note.
Submit Enhancement Requests-
If there's a feature that you would really think should be part of Tcl
or Tk, submit a Request For Enhancement (RFE) report. Before you
actually submit the report, you should post a Request For Comments
(RFC) on comp.lang.tcl so that other community members can help
evaluate your feature request. This will also give community members
an opportunity to direct you to existing extensions that provide the
feature you want; or to help in the development of the new feature.
Once your feature request has passed peer review within the community,
submit it via the
bug
report form.
Fix Bugs-
If there's a bug that you really want to see fixed, go ahead and fix
it! Make a patch and submit it in a bug report. The best patches are
both correct and complete. What makes a good patch
good?
Implement Enhancements-
If there's a feature that you really want to see implemented, feel
free to implement it yourself. Make a patch and submit it in a
Request For Enhancement (RFE) report. RFE patches should be correct
and complete, and should not introduce any new bugs. What makes a good patch good?
What makes a good patch good?
Good patches share two features: correctness and completeness.
- Correctness
-
The patch should fix the bug it is trying to fix, or
implement the feature it is intended to implement. But it is equally
important that the patch does not introduce new bugs. The Tcl/Tk core test
suite
provides a good way to verify that your patch has not introduced new
bugs. While developing your patch, and once it is completed, you
should run the entire core test suite on at least one of three supported
platforms (Unix, Macintosh, and Windows) to verify that your patch has
not introduced new bugs.
If your patch is intended to fix a bug, you should create a test case
that exposes the bug before writing the fix. Then
use that test case to verify that the bug is in fact fixed by your
patch.
- Completeness
-
A complete code patch has three components: code, tests, and
documentation. Ideally, it includes code to fix the bug or implement
the feature on each of the three supported platforms (Unix, Macintosh,
and Windows). Of course, not everybody has access to development
environments on all of these platforms. Don't let this discourage you
from submitting patches; just submit code for as many platforms as you
can.
Besides the source code itself, the patch should include new test cases
for the Tcl/Tk core test suite. These tests should exercise every
line of the new code. You can read the
Tcl Style Guide for information about
writing tests, and you can look at the Tcl/Tk core test suite tests
for examples of how to write tests using the tcltest package.
Finally, the patch should include documentation. If the patch is a
bug fix, there may not be any new documentation, although you should
be sure that the documentation is still accurate and up-to-date with
respect to the code patch. If the patch is an enhancement patch,
there should be new documentation explaining the use of the new
feature, restrictions of the implementation, and any other relevant
information.
Remember, the more of these components that you provide, the faster
your patch can be integrated with the Tcl/Tk core itself.
In addition, C code should adhere to the C
Style Guide coding standard; Tcl code should adhere to the
Tcl Style Guide coding standard. If
possible, patches should be created using the utility
diff, as in diff -u originalFile
newFile. Patches submitted in this format are much easier to
work with and apply. diff is a standard utility on
UNIX-based systems, and versions are available for Windows as well.
|
