Author: Don Porter <dgp@users.sourceforge.net>
State: Draft
Type: Informative
Vote: Pending
Created: 23-Feb-2001
Post-History:
Abstract
This document presents information and advice to maintainers in the form of a Frequently Asked Questions (FAQ) list.
Preface
Notice in the header above that this is a Draft document. It won't be the official word of the TCT unless/until it is accepted by the TCT. Meanwhile, it should still be a helpful guide to those serving or considering service as maintainers. At the very least it's a useful straw man to revise into something better. Help us make it even more useful by using the [Edit] link at the bottom of this page (if any) to add/revise the questions and answers, or add your comments.
Background
TCT procedures (see [0]) calls for one or more maintainers to take responsibility for each functional area of the Tcl ([16]) or Tk ([23]) source code. Every source code patch to Tcl or Tk will be committed to the official branches of the appropriate CVS repository only after approval by an appropriate set of maintainers.
Can I be a Tcl/Tk maintainer?
Most likely. To be a maintainer, you should have...
...an interest in Tcl/Tk.
...access to the Internet (Web and e-mail).
...some volunteer time to contribute.
...the ability and the support software to code in C and/or Tcl, use CVS, use SourceForge facilities, and familiarity with a portion of the Tcl/Tk source code to be maintained, or the willingness to acquire these things.
For the most part, if you are reading this document, you probably have what it takes to be a Tcl/Tk maintainer.
What can I maintain?
The Tcl Core Team (TCT) has divided up the Tcl/Tk source code into functional areas as described in [16] and [23]. You can volunteer to help maintain as many areas as you think you can handle. Select those you have experience with or an interest in.
What does a maintainer do?
Maintainers are the people who make changes to the files that make up the source code distribution of Tcl or Tk -- code, documentation, and tests. That's what a maintainer does: check in changes to the official source code in the area he/she maintains.
The source code can be changed for several reasons: to correct a bug, to add a new feature, or to re-implement an existing feature in a new way. The reason for a change controls how much oversight the maintainer must have while making the change. More on this below.
How do I prepare to be a maintainer?
The official repositories of Tcl and Tk source code are kept at SourceForge, so you need to register for a SourceForge account https://sourceforge.net/account/register.php . As part of the registration, you will select a login name. When you volunteer as a maintainer, the administrators of the Tcl or Tk projects will need that name to give you write access to the appropriate repository.
Once you have a SourceForge account, get familiar with the tools it provides. Most important is that you get set up to use CVS over SSH to access the repository. This can be difficult. There are some notes http://tcltk.org/sourceforge on how other Developers on the Tcl and Tk projects have been able to successfully get this done.
This document does not include instructions on how to use CVS. See the following references for assistance with learning CVS.
Add more references here please.
How do I volunteer to be a maintainer?
Send a message to tcl-core@lists.sourceforge.net telling the TCT your SourceForge login name and what area(s) you want to help maintain. Someone will add you to the list of Developers on the Tcl or Tk projects and enable your access to SourceForge features like the Bug Tracker and Patch Manager. As a Developer, you will have write access to the appropriate repository of official source code.
Write access! So I can just start changing Tcl/Tk?!
For some purposes, yes. For others, you'll need to get approval from the TCT first. Read on...
What Internet resources does a maintainer use?
A maintainer uses the SourceForge Bug Tracker for Tcl or Tk to learn what bugs are reported in his area (browse by Category).
A maintainer uses the SourceForge Patch Manager for Tcl or Tk to learn what patches make changes in his area (browse by Category).
A maintainer uses CVS via SSH to access, track, and modify the various branches of development in the repository of official Tcl or Tk source code.
cvs -d :ext:username@tcl.cvs.sourceforge.net:/cvsroot/tcl \
checkout -r $BRANCH_TAG -d $LOCAL_DIR tcl
cvs -d :ext:username@tktoolkit.cvs.sourceforge.net:/cvsroot/tktoolkit \
checkout -r $BRANCH_TAG -d $LOCAL_DIR tk
A maintainer examines the state of Tcl Improvement Proposals (TIPs) and adds his comments to them at the TIP Document Collection.
A maintainer may follow and participate in TCT discussions about TIPs and other matters concerning Tcl/Tk development on the TCLCORE mailing list.
A maintainer may receive e-mail notification every time any change is made to any entry in Tcl's or Tk's Bug Tracker or Patch Manager by subscribing to the TCLBUGS mailing list.
There are multiple maintainers in my area. What do I do?
The maintainer tasks are the same; you just have more hands to get the job done. It is up to the maintainers of an area to decide among themselves how they will divide the tasks. They might each take on a particular subset of files. Or they might let some maintainers fix bugs while others review new features. Or they might appoint one maintainer as the lead and let him assign tasks to the others. Whatever works for you, and gets the work done.
I found a bug in my area. What do I do?
Bug finding and reporting is a job for the whole community, so when you find a bug, take off your maintainer hat. Report it to the Bug Tracker just like anyone would. If you recognize that the bug is in your area, go ahead and assign it to the Category for your area and to yourself or one of the other maintainers who share responsibility for that area.
Why do I report the bug to myself?
So that the bug appears in the database. Someone else may find it too, and when they go to report it to the Bug Tracker, they should discover that it's an already reported problem. A registered bug report is also the place where progress on fixing the bug can be recorded for all to see.
There's a bug reported in the Category for the area I maintain. What do I do?
First, understand the bug report. The best bug reports are clear and come with a demonstration script, but not all reports are so well crafted. You may need to exchange messages with the person who reported the bug. If the reporter logged in to SourceForge as username before submitting a report, then you can write back to username@users.sourceforge.net. If the bug was reported by nobody, the best you can do is post a followup comment to the bug asking for more information, and hope the reporter comes back to check.
Next, confirm that the bug report is valid, original, and that it belongs in your area. Does it correctly assert that some public interface provided by your area behaves differently from its documented behavior? If not, then you should take the appropriate action:
If the bug report notes a problem in another project, assign it to a Developer who is an Admin of the other project. Add a comment asking them to reassign to the correct project. Assigned To: an Admin of the other project.
If no Developer is an Admin of the other project, or the other project isn't hosted by SourceForge, note the error in a comment, and mark the report invalid. Resolution: Invalid; Status: Closed; Assigned To: yourself.
If the bug report notes a problem due to a bug in another area, reassign it to the appropriate Category. Category: correct category
If the reporter's expectations are incorrect, point them to the documentation. You may also want to revise the documentation if it is not clear. Resolution: Invalid; Status: Closed; Assigned To: yourself.
If the bug report notes a problem already noted by another bug report, note the duplication. Resolution: Duplicate; Status: Closed; Assigned To: yourself.
If the bug report acknowledges that the code is behaving as documented, but argues that the documented behavior should be revised, then the report is a feature request rather than a bug report. More on handling feature requests below. Group: Feature Request.
Valid, original bug reports in your area should be assigned to a maintainer of your area. If you are the only maintainer of your area, assign the bug to yourself. If there are multiple maintainers, you should decide among yourselves how to divide up the bug report assignments.
There's a bug assigned to me. What do I do?
Now we get the the heart of what a maintainer does. This is where you unleash the energies and talents you bring to the table. So, the best answer is "Do what works best for you." The rest of this answer should be read as additional guidelines and tips that have worked well for others and might help you, but not as a mandatory checklist you must follow. If some advice below seems more burdensome than helpful, fall back to "Do what works best for you." The goal is to register a patch that fixes the bug with the SourceForge Patch Manager. Do whatever helps you accomplish that goal.
Try to enlist the assistance of the person who reported the bug. This is especially important if the problem is platform-specific on a platform you do not have access to. Gaining the participation of the person who reported the bug can have many other benefits too. They see that progress is being made. They can offer additional insights they have, but left out of their original report. They can see how better bug reports lead to faster, better solutions, so their next reports may be of higher quality. They may even gain enough experience that their next report may come with the correction already attached. Eventually, they may even become maintainers themselves.
First, try to develop a test that demonstrates the bug and add it to the section of the test suite for your area. If the original bug report contained a demonstration script, perhaps you can adapt that. The new test will help you verify when you have fixed the bug.
If a fix for the bug is offered with the report, give it a try. Otherwise develop a fix yourself. Take care that while fixing the bug, you do not create new bugs by changing the correct behavior of other parts of the code in your section. The test suite for your area is very helpful. Use it.
It may become apparent that the best fix for your bug can only be accomplished after another bug is fixed first, or perhaps after a new feature is added to Tcl/Tk. In those cases, add a comment to the original bug report so those interested will know what is causing the delay. SourceForge may offer a way to denote these dependencies as well.
If you have trouble fixing the bug, ask for help. Try the other maintainers of your area first. Then try posting comments attached to the original bug report. Using cvs log, you can get a list of developers who've recently made changes to the files you maintain. They might be able to offer advice, or explanations about why the code is the way it is. If none of these focused searches for help bears fruit, then try broader requests to the TCLCORE mailing lists, or the news:comp.lang.tcl newsgroup.
At any time, you may have several bugs assigned to you. It will help guide the expectations of the Tcl community if you can assign priority values to the bugs indicating the importance you assign to them. Try to work on fixing higher priority bugs before lower priority bugs. Some reasons you might give a bug a higher priority include:
1. The bug causes a panic or core dump.
1. Documentation is missing or incorrect.
1. Other bug fixes are waiting on this bug fix.
1. Several duplicate reports or "me too" comments about the bug
are coming in from the community.
Some reasons you might give a bug a lower priority include:
1. A workaround is identified \(add it as a comment attached to the
bug report\).
1. Feature requests tend to get lower priority since they should
be handled through the TIP process.
Once you have crafted a fix for the bug, create a patch to the official source code (including the new tests that test for the fixed bug) and register it with the SourceForge Patch Manager. Note the number of the bug report fixed by the patch somewhere in the summary or comments associated with the patch. Assign the patch to yourself. Assign the Category to the area you maintain.
There's a patch registered under the Category I maintain. What do I do?
The SourceForge Patch Manager is used to review and revise patches before they are committed to the official source code. Your actions depend on what the patch does to your area, and who the patch is assigned to. The patch may change the public interface provided by your area (feature change); or the change may be completely internal (bug fix, or re-implementation) within your area. The patch may be assigned to you, to someone else, or to nobody. The person the patch is assigned to is the person who is leading the effort to integrate the patch into the official source code.
What if the patch is assigned to nobody?
The patch has probably been contributed by someone not on the list of Developers. It may be a contributed bug fix, or a contributed implementation of a TIP. Assign contributed bug fixes to the same maintainer who is assigned the corresponding bug report. If there is no corresponding bug report, add one. Assign TIP implementations to the Developer identified in the TIP as the one responsible for implementation of that TIP, or the TCT member who sponsored the TIP.
If the patch changes only your area (and shared or generated files), then leave the Category in your area. If the patch changes other areas as well as yours, change the category to None.
What if the patch is assigned to me?
Presumably you've assigned it to yourself to indicate that you're taking charge of integrating that patch into the official sources. If that's a mistake, treat the patch as if it were assigned to nobody. If you are the one leading the integration effort, see below (How do I integrate a patch into the official sources?).
What if the patch is assigned to someone else?
If the patch is assigned to another maintainer in your area, let him handle it. Leave it alone.
If the patch makes no changes in your area, change the Category of the patch to None.
If the patch makes changes in your area, and is assigned to a Developer who is not a maintainer of your area, that Developer is asking for review of the patch's changes to your area. You or one of the other maintainers of your area should review the patch and accept or reject it. Read on...
What special review does a "feature change" patch require?
Changes to the public interface of your section must be proposed to and accepted by the TCT through the TIP process before they can be added to the official Tcl source code. If the patch changes the public interface of your section, then there should be an associated TIP describing the new feature(s) that patch implements. Until there is such a TIP, and that TIP has been accepted by the TCT (check the value of the State header), you should not approve the patch.
Once there is an approved TIP corresponding to the patch, you should confirm that the patch correctly implements the accepted feature as described by the TIP. If not, you should not approve the patch.
After confirming that the patch correctly implements the feature change described in an accepted TIP, you should still review the technical merit of the patch's changes to your area before approving it.
How do I review the technical merits of a patch?
Apply the patch and run the test suites that cover your area. Check that the patch does not add any new test failures. If the patch is a bug fix, check that it actually fixes the bug. Think five times before approving a patch that causes new test failures or incompletely fixes a bug or incompletely implements an approved TIP.
Keep in mind that once the patch is integrated into the official sources, you'll be expected to maintain it. It is not in your interest to approve patches that make your job harder. Think four times before approving a patch that you do not understand.
Check that the patch keeps the features offered on different platforms consistent. If not, be certain that the documentation properly notes the platform-specific behavior. Think three times before approving a patch that causes the capabilities of Tcl/Tk to further diverge on different platforms.
Check that the patch follows Tcl's established coding conventions. See the Tcl/Tk Engineering Manual http://purl.org/tcl/home/doc/engManual.pdf and the Tcl Style Guide http://purl.org/tcl/home/doc/styleGuide.pdf for details. This is especially important when accepting contributed patches. Think twice before approving a patch that doesn't conform to these conventions.
Check the effect of the patch on the performance of Tcl/Tk. Use the tclbench set of benchmarks.
cvs -d :pserver:anonymous@tcllib.cvs.sourceforge.net:/cvsroot/tcllib \
checkout tclbench
Think carefully before approving a patch that significantly degrades the performance of important operations.
Finally, while examining the patch, you may see a better way to accomplish the effect of the changes in your area. If you can provide that alternative implementation reasonably quickly, then propose it as a revision to the patch. However, be careful not to let the perfect be the enemy of the good. If a patch works, do not reject just because you can imagine a better way it could be done. Provide the better way, or accept the less good way in the patch, and leave migration to the better way for later when you have the time.
To approve the patch's changes to your area, simply note your approval in a followup comment on the patch. Indicate in your comment the Category of the area for which you approve the changes. If the patch changes multiple areas, set the Category of the patch back to None.
To reject the patch, you also indicate your rejection in a followup comment. You should explain the reasons for your rejection so that the patch can be revised with the goal of gaining your approval. If you can supply the needed revisions with reasonable effort, do so. If the patch changes multiple areas, set the Category of the patch back to None.
Unless the patch is assigned to you, do not change the Status of the patch. Leave that to the Developer assigned to the patch.
How do I integrate a patch into the official sources?
First you need the approval of at least one maintainer of each section changed by the patch.
How do I get approval for integration?
First, assign the patch to yourself to indicate that you are leading the integration effort. Next, determine the list of categories corresponding to the areas changed by the patch. It may help if you list them in a comment attached to the patch.
For each category in the list, assign the Category of the patch to that category. Then wait for a maintainer for that area to review the patch. If one approves it, then assign the next Category in the list. If maintainers for all areas on the list approve the same patch, you may integrate the patch into the official sources.
If a maintainer rejects the patch, revise the patch to address his concerns. Then start the review again. Start with the maintainer who rejected the first patch to be sure his concerns are addressed first.
Note that if the patch changes only the area you maintain, then you may immediately integrate the patch into the official sources once you are satisfied with it and it is registered in the Patch Manager.
The patch is approved. How should it be integrated?
Get a CVS working directory that is up to date with the HEAD branch of the official source repository. Apply the patch to your working directory, and then 'cvs commit' the changes to the HEAD branch.
At the same time you commit the patch, be sure to add an entry to the ChangeLog file describing the change. Follow the established format, which is derived from the GNU coding conventions. The description should be brief, but should describe the change reasonably completely. Include the SourceForge Bug and Patch ID numbers in the ChangeLog entry, but do not assume that the reader will have access to the Bug Tracker and Patch Manager to be able to understand the entry. You may assume the reader has access to the documentation.
Finally, with the patch integrated, change the Status of the patch in the Patch Manager to Accepted. If any bugs were fixed by the patch, change their Resolution to Fixed, and their Status to Closed.
I want a patch review even though the patch changes only my area.
Keep in mind that integrating a patch into the official sources is not an irreversible act. Commits to the HEAD branch will be checked out and tested by members of the Tcl community who are tracking Tcl/Tk development. Alpha and beta releases of Tcl/Tk that include your patch will also get your changes reviewed in practical settings.
That said, if you really want a pre-commit review of your patch, you can add a comment to the patch asking for review. Someone will probably respond. It's up to your judgment how long to wait, keeping in mind that you are the maintainer, so your judgment on the quality of patches in your area is implicitly trusted.
What about CVS branches?
When you integrate a patch into the official source code, you will usually 'cvs commit' the patch onto the HEAD branch. If the patch includes a feature change, it must (except in unusual circumstances approved by the TCT) be committed to the HEAD branch. The HEAD branch is the development branch from which alpha releases of Tcl/Tk are generated.
At any time, there is also one or more stable branches of development. As of February, 2001, the branch 'core-8-3-1-branch' indicates the sequence of revisions from which the 8.3.x releases of Tcl/Tk are generated.
Since the Tcl Core Team took over development of Tcl/Tk, no changes have been committed to a stable branch, so we really have not established procedures on how we will decide what bug fixes should and should not be applied to the stable branch. It is possible that maintainers will be involved, though. It is also possible that a special team will be appointed to update the stable branch in preparation for the next stable release. In the case that you as a maintainer are asked to commit to the stable branch, be aware that the only patches that should be committed to a stable branch are those that fix bugs. No new features should be committed here.
The other kind of branch is a feature branch. This is a development branch on which a sequence of several revisions may be committed as work in progress on a new feature, or re-implementation of existing features. Typically a feature branch will be created if the effort...
...touches on several functional areas;
...is worked on jointly by several Developers;
...is complex enough to require several revisions;
...needs prototyping to determine the best TIP proposal to make; or
...makes an incompatible change to Tcl/Tk that properly belongs on the next major version of Tcl/Tk before the HEAD branch has been designated for work toward the next major version.
As a Developer, feel free to create a feature branch if you have a reason to use one. Make a note of your branch tags in [31]. Avoid the use of a branch tag matching core-* . Save the core-* branch tags for the tags of official stable branches and releases. To avoid conflict with other Developers, consider using your SourceForge login name as a prefix on the feature branch tags you create. Try to also make the branch tag descriptive of the purpose of the branch.
One big advantage of a feature branch is that any Developer may commit changes to a feature branch without all the publication, review, and approval overhead required when committing patches to the HEAD or stable branches. On the feature branches you can go through multiple revisions reasonably quickly and spend the administrative overhead only at the end when it is time to apply the finished product to the official branches.
What other things does a maintainer do?
The tasks of fixing bugs and approving and committing patches to the official source code of Tcl and Tk are the core tasks that maintainers perform. That's all the job actually requires.
You will probably want to keep an eye on the TCT's plans for Tcl/Tk development as well. If a TIP proposes a new feature in your area, it is in your interest to know about it, and propose revisions and improvements to it. Ultimately you will be asked to approve the patch that implements the new feature, and then you will be expected to maintain it, so if you have concerns about a proposal, it's best to make them known early. TCT members will probably ask your opinion on TIPs that propose changes to your area for this reason.
Comments
Please add your comments here.
Well, since I drafted this SourceForge has replaced the Bug Tracker and Patch Manager with a Tracker. This TIP really needs revision now.
Copyright
This document has been placed in the public domain.