Version 1.0 John Todd, Brian K. West, Mark Spencer
Jan 8, 2004
So, what is the purpose of the bugtracker?
To track bugs, features, and miscellaneous (documentation) elements
that need to be discussed in a permanent, semi-threaded manner and
which can more easily store programmatical or textual difference
files ("diff -u") in a manageable way. The bugtracker is designed to
allow the user community to work on different issues so that the
brunt of the work is moved from the shoulders of the small
development staff onto the more distributed group. The _primary_ use
of the bugtracker system is to track bugs, where "bug" means anything
that causes unexpected or detrimental results in the Asterisk system.
The secondary use is to track feature requests, which are not as
critical as bugs and which will receive second priority in all cases.
The third reason is to track some of the miscellaneous issues
surrounding Asterisk, such as documentation and commentary.
Bugs: What to do?
The following information is necessary for you to submit a bug
properly in a manner that will get it repaired in the shortest
possible time:
CVS version ("show version") - if this is not the most updated
CVS, why not? Have you tried it?
What distribution of software are you running? What version?
("Linux Redhat 9.0" as an example.)
Is the problem reliably repeatable? If not, you'll need to be
EXTREMELY detailed in giving your configuration notes and including
as much debug information as you possibly can, as non-repeatable
problems tend to be almost impossible to guess resolution types.
See the notes below on "valgrind" and "gdb"
Include all your outputs from various traces, debugging, etc,
as attachments and NOT as pasted text in the bug report. The
bugtracker does funky things with line wrapping, etc. and an attached
file makes more sense.
MAKE SURE THE BUG DOESN'T EXIST ALREADY. Please be diligent
in reading all of the possibly relevant bugs. This may take some
time, but duplication is a real pain. Plus, in reading the other
bugs you might find something useful. :-)
Now that you've done all that, make sure to include all relevant
configuration files. Don't just give short snippets; very often
there are extremely important things in the config files that you
think aren't important, but hold the key to the problem.
If people who are testing the bug cannot replicate it on their own
machines, you may be requested to have someone log into your system
to take a look around. Of course, it is your discretion that allows
this type of access, but it will speed up the process greatly.
I have this new feature...
We all love new features, but new features bring new complexities,
and new complexities bring new bugs. So, to help cut down on new
bugs being introduced with your new features, please consider as much
of what you're touching as possible. In other words: everything is
linked in very subtle ways; make sure you look very closely at each
piece of what your patch influences before you submit it. Don't be
afraid to submit revised copies of the patch if that's what's
required.
I'm not a programmer, but this feature would be great...
Not a programmer? Have a feature idea? That's fine, but don't
expect to see it anytime soon unless you put a bounty on it (see
"bounty" below.) If you do decide to put in a request for a feature,
please make sure you think about it completely. Where you can, put
examples of what the relevant config file changes might look like, or
the error messages the change might print out. Please include
specific reasons as to why the change is required, not just by you,
but by others who might encounter the same situation. Please do NOT
submit general, vaporous feature requests like "I think Asterisk
should have a better interface!" Non-specific requests will be
unceremoniously deleted by the admins, and you will receive negative
kharma points.
In summary: think about your feature. Think about it some more.
Ask some people on the IRC channel
(http://www.asterisk.org/index.php?menu=support#irc
) about it. Wait
a few hours, re-read your offline text, and think some more. Wait.
Think about it one more time. Then post the feature request to the
bug tracker.
Testing a patch
After you create a new feature or bug patch submission, it will
need to be tested before it can go into CVS. By "tested", we mean
that multiple persons other than yourself should patch/run/abuse the
patch in various manners so that all possible variations of
input/output are run through the test. In instances where there are
limited test environments, please document exactly how and why you
were unable to get others to test the patch so that the developers
know that this simply isn't "waiting for testing" and is in fact
ready to go. Insufficient testing is a sure way to have your feature
put on the back burner - the CVS maintainers don't have time to run
exhaustive tests on each new feature. Find people on the #asterisk
IRC channel who may be useful/clueful enough to test things for you,
and develop a working relationship with other Asterisk users so that
you can swap testing routines; this greatly speeds the process.
So, my feature [was good, was tested, cured cancer] but it still
didn't make it into CVS! What can I do?
Many times, a feature that might sound good to you and might work
as expected just isn't important enough to make it into the system if
it isn't deemed useful to a large enough audience. This is, of
course, a subjective decision by the CVS maintainers. Their opinions
can be swayed if enough users get together and rally around a
particular feature that seems to be useful to them, so getting others
to chime in on your neat request will perhaps advance it further
towards the top of the queue, or get it included where previously it
was not seen as useful to anyone other than yourself. Sometimes,
it's just a matter of timing - nobody has had the time to look at it
yet. It's perfectly legitimate (and good) for someone who has a bug
or feature request to go to IRC and lobby for it with the bug marshal
to try to push it through, schedule time, etc.
Methodology/Netiquette of Patches
It is common use on the Asterisk bug tracker to put the text
(minus quotes, but including brackets) of "[patch]" as the first part
of a bug short description when the particular bug includes a
sourcecode patch. This helps the developers sort things
appropriately (we'll let you guess which bugs get worked on first.)
Please use "diff -u" on all your patches. Patches which include
alternate formatting are almost certainly going to be thrown out or
ignored; there are too few hours in the day to wade through
difficult-to-follow C code fixes without the help of "diff -u"
Please use the newest version of CVS code for the appropriate
branch of the tree when you submit changes. Very often, problems are
fixed in the latest version of the code, and you might be fixing
something that is already a known and repaired issue, so a rule of
thumb is to either use CVS code that is less than 24 hours old when
you submit patches
Use complete sentences, capitalization, and avoid slang. This
especially applies to non-native English speakers who may have picked
up bad habits from IRC channels. Bad English is not a problem, but
bad English learned from IRC is worse (i.e.: "d00d, zaptel is
fux0red!") The ability of others to understand your comments
directly corresponds to rapidity of reply.
Please include output from "sip debug" if you have a SIP problem.
This seems obvious, but apparently is not.
Any patch or bugfix that has a bounty on it should have (minus
quotes, including brackets) the term "[bounty]" at the front of the
short description line.
Delete older versions of your patches or files on a ticket if you
have updated them to newer versions. Too many versions gets very
confusing.
Patches and large debug messages should be attached as files, not
pasted into the comments area.
What can I do to help?
There are some obvious things you can do to help the process along.
If you're not a programmer, you can still help. Pick some bugs that
have patches, and patch a copy of Asterisk. (We assume that even if
you're not a programmer, you can "patch -p0 < patchfile.blah" and
re-compile.) Test the patch. Run it on your hardware, and comment
on the ability of your system to work or not work with that
particular patch or bug. There will probably be bugs in the system
which have more discussion than others, and they may effect you -
comment on them, if commentary is timely and useful. Just as
importantly, if someone reports a bug in some way that they think
they can replicate, try to replicate it. If you can, say so. If you
can't, say so. There are a huge number of tickets that get opened on
phantom bugs, because someone's configuration is broken, or they have
bad hardware, or what-have-you; the project needs more people simply
verifying what someone has said to be a problem, or disproving it as
not being a problem in all instances.
If you are a programmer, your patches are desired. Make sure that
there is not already a patch waiting in the system that does the same
thing, as is often the case. Then, submit the patches and start a
test cycle with some other users, as described above.
If you really want to help out and show a lot of promise in the
field of arranging bugs and commenting on them, it is possible for
you to get write permission into the bugtracker. This will allow you
to close/comment/alter bugnotes. Talk to one of the current bug
marshals (as they're called) or one of the Digium folks about this if
you have such a desire. This implies that you have about 6-10 hours
a week to herd the bugs and then work with various developers in
getting the bugs resolved or closed out.
Hey! My bug/patch was closed out and it's not fixed!
The bug marshals will try to get more data on a bug if there
insufficient commentary or debug information given in the ticket. If
there are questions posted as followups to your bug or patch, please
try to answer them - the system automatically sends email to you
every time a bug on which you've commented has been updated. If the
original poster of the patch/bug does not reply within some period of
time (usually something like a month) and there are outstanding
questions, the bug/patch may get closed out, which would be
unfortunate. If your bug is determined to be a configuration error
or something that is clearly not reproduceable, it may be closed
immediately by a bug marshal. If you believe this to be in error,
please go in and edit the bug and say so, or comment to the bug
marshal that made the closure (visible on the ticket itself.) If
that fails, bring it up on the mailing list(s) and it will be sorted
out by the community.
So what's this about a bounty on bugfixes?
It is the case that some corporate users of Asterisk will pay you
hard cash for your work on developing patches and bugfixes. Often,
there are reasons that a firm can't or won't fix/patch Asterisk
internally, and wants to outsource that work to the larger Asterisk
community. These patches follow the same GPL rules as everything
else for Asterisk that is submitted to the bugtracker: if the author
has signed a disclaimer, and the patch is in the bugtracker, it's
considered fair game to be included in the modified GPL version of
Asterisk that Digium maintains. The Asterisk community wins whenever
a bounty bug is resolved because everyone benefits from that work.
The company sponsoring the bounty wins, because their specific
problem is fixed. And, of course, the programmer wins because
they're paid. Bounty arrangements are between the sponsor and the
programmer, and are NOT via Digium or any other third-party
middleman. Payment terms, guarantees, etc. etc. are the problem of
the two parties (programmer and bounty sponsor) and the bugtracker
simply permits an open forum for discussion of the problems and for
the bounty. If there are multiple resolutions to a bounty, it is the
sponsor's sole discretion to award the payment or not. As noted
above, any feature request or bug report that has a bounty bounty on
it should have (minus quotes, including brackets) the term "[bounty]"
at the front of the short description line. All bug reports that are
bounty oriented will be public and GPL, and we will actively
discourage/delete non-GPL arrangements that are based on bug reports
in the open-community bugtracker (i.e.: you will incur the wrath of
the bug marshal posse.)
The Disclaimer
All patches and features (and commentary, for that matter) are
assumed to be "public use" once on the bug tracker. If you have not
signed a waiver, your code will NOT GET INTO CVS. Please see
http://www.digium.com/disclaim.changes or
http://www.digium.com/disclaimer.txt and
sign/fax the document back
to +1-256-864-0464. Please be sure to include your "screen" name if
you are submitting issues to the bug tracker under a different
pseudonym that is non-obvious. You may be asked to verify your
pseudonym via email. The reason for the disclaimer has been
discussed many times, but the general gist is that your contribution must not
introduce any encumberance to the Asterisk code base,
but Digium DOES NOT OWN
your contribution, and they cannot take released Asterisk out of GPL. Relax; it's
a very fair and reasonable disclaimer, and does not remove your
rights or threaten the open source nature of the project. See the
mailing list archives for long explanations of why everyone who
contributes agrees that it's a fair and sane thing to do. You only
need to sign the disclaimer once; it applies to all stuff that you
send in via the bugtracker.
Summary:
What will slow down my bug/patch from being looked at:
No patch code (for features or some bugs)
Poor descriptions
No backtrace or debug information (in crash instances)
No followup to questions by others
Not having a disclaimer on file with Digium
What will speed up my bug/patch being implemented?
Testing by 1 or more others to reproduce events or use patch
Good discussion by others in the bug notes
Clear C code with excellent comments
Clear debugging packet traces (for protocol-level VoIP issues)
What does the Asterisk community need?
More testing by everyone to keep developer head-scratching time
to a minimum