Bugreport template and description file

[Jens Skripczynski]

Hi,

at the moments there are a lot of bugs in the developement version
of samba. 
People notice them and report them. But sometimes they forget some necassary
information, that makes it harder to find the actual bug, or in some small
cases appear a user error.

To improve this i made a first scatch of a bugreport template text file and
a file describing all the fields. I hope by having categories in those files,
and knowing what information is necassary and how to find it, that this
improves the speed of the development of the new samba versions.

P.S.: If you find any seplling mistakes, some better way of saying things or
      even want to add something, feel free to mail me.

P.P.S.: Lars can you add these files to the FAQ ? thx.

Ciao

Jens Skripczynski
-- 
E-Mail: skripi at igd.fhg.de

Computers are like airconditioners: They stop working 
properly if you open windows.
Win95:        A 32-bit patch for a 16-bit GUI shell running on top of an
              8-bit operating system written for a 4-bit processor by a
              2-bit company who cannot stand 1 bit of competition.
-------------- next part --------------
 G E N E R A L                  |
--------------------------------+

Before you send a bugreport to the list, please make sure that you
have the latest samba code. 

If you are using cvs, it is sometimes possible, that your local sourcetree 
isn't in sync with the cvstree anymore. You will have to remove all source
files and do a fresh checkout.

For a fast responce and efficient bug tracking it is mandatory, that you
responce the following questions as soon as possible, as the guys of the samba
team have a lot to do, and each minute you invest may save them hours of work
( and giving the error a higher priority).

__

have patience!  remote debugging is often slow, and may take place over
several days.

Always communicate *full* context information.  The developer may be
expecting to deal with between fifty and a few hundred email messages:
Present them with as much information as they will need to make instant
context-decisions, instead of wading through piles of previous messages
they may waste precious time searching for.  Even an hour is often enough
to forget what was said and sent.
__

Typing:
Things separated by a "|" symbol are an or combination. So (A|B) means you
can choose "A" or "B".
A "$WORD" Means substitute $WORD by your local conditions
`command -option` means execute the command with the options

general Information             |
--------------------------------+

OS: Please submit the Operating System you are using with Version number.
    ex: - Linux (Suse|Redhat|Mandrake) $VERSION $KERNELVERSION
        - SPARC $VERSION
        - ....
   `uname -a` typed in your shell should reveal most information. If not
   "ask your local system administrator... ;)"

Compiler: The compiler you are using. Even if samba is written Posix complient
          it may happen, that some compilers do make a difference on
          interpreting code.
     For the gcc compiler `gcc -v` reveals the version number.
     For others consult the man page. `man $COMPILER`

CVS-Branch: Contains the CVS-Branch you are Using. Valid itmes are:
            SAMBA_TNG|SAMBA_2_0_RELEASE|SAMBA_2_0|HEAD

Version/Date: Contains either the Version number of the tar-ball you got from
              the official samba ftp or http server, or if you are using cvs,
              the date _and_ time of your last update (don't forget to mention 
              the timezone).

error Type   : reproduceable | random
               Is the error type. Reproduceable errors have the highest
               priority, as they can be tracked down easier. Random errors
               are more a call for someone to go fishing in the mist.

Short Desc.   : A short description when the error occurs. Logon, accessing a
                share / printer, joining the Domain etc.

Trigger        : How to trigger the error. "If i click on the Internet Explorer
                 my Harddisk catches fire...."


special Information             |
--------------------------------+

If you catch in your log-files something like: "INTERNAL ERROR... see
Bugs.txt". Then you have to compile samba in a special debug mode:
If not continue with 4).

1) recompile with debug information :
        + cvs update
        + make distclean
        + ./configure.developer
        + make
        + make install
        + edit smb.conf: Change "debug level = 100"
        + restart all samba daemons

2) If it core dumps again with : "INTERNAL ERROR... see Bugs.txt". Else
continue with 3).
 `gdb $PROCESSNAME core`
 + type where
 + again send E-Mail as noted above with the information of gdb

3) attach the full log-files of the corresponding daemon 
   But keep them _short_, and _relevant_!  
   3mb Log files containig just 100 (!) relevant lines are no use.
   Sending log files from start-up, when access to one file is the only 
   trigger is also unhelpful, although in some cases this _may_ be desirable, 
   it depends on the problem.


4) Supply if possible relevant traffic going over the wire. Useable tools
   for this are `tcpdump` on the Unix/Linux side and netmon trace (version 1)
   on the Windows side.

5) attach you configuration files. Usually the smb.conf should suffice.


-------------- next part --------------
   G E N E R A L
  * * * * * * * *
-------------
OS          :
-------------
Compiler    :
-------------
CVS-Branch  :
-------------
Version/Date:
-------------
Error Type  :
-------------
Short Desc. :
-------------
Trigger     :
-------------

   S P E C I A L
  * * * * * * * *

-------------
GDB         :
-------------

-------------
Log-Files   :
-------------

-------------
smb.conf    :
-------------

---------------
tcpdump/netmon:
---------------