gdb/CONTRIBUTE

   1
   2                         Contributing to GDB
   3
   4 GDB is a collaborative project and one which wants to encourage new
   5 development.  You may wish to fix GDB bugs, improve testing, port GDB
   6 to a new platform, update documentation, add new GDB features, and the
   7 like. To help with this, there is a lot of documentation
   8 available.. In addition to the user guide and internals manual
   9 included in the GDB distribution, the GDB web pages also contain much
  10 information.
  11
  12 You may also want to submit your change so that can be considered for
  13 conclusion in a future version of GDB (see below).  Regardless, we
  14 encourage you to distribute the change yourself.
  15
  16 If you don't feel up to hacking GDB, there are still plenty of ways to
  17 help!  You can answer questions on the mailing lists, write
  18 documentation, find bugs, create a GDB related website (contribute to
  19 the official GDB web site), or create a GDB related software
  20 package. We welcome all of the above and feel free to ask on the GDB
  21 mailing lists if you are looking for feedback or for people to review
  22 a work in progress.
  23
  24 Ref: http://sourceware.cygnus.com/gdb
  25
  26 Finally, there are certain legal requirements and style issues which
  27 all contributors need to be aware of.
  28
  29 o       Coding Standards
  30
  31         All contributions must conform to the GNU Coding Standard.
  32         http://www.gnu.ai.mit.edu/prep/standards_toc.html
  33         Submissions which do not conform to the standards will be
  34         returned with a request to reformat the changes.
  35
  36         For GDB, that standard is more tightly defined. GDB's
  37         coding standard is determined by the output of
  38         gnu-indent.
  39
  40         This situation came about because, by the start of '99,
  41         GDB's coding style was so bad an inconsistent that it was
  42         decided to restart things from scratch.
  43
  44
  45 o       Copyright Assignment
  46
  47         There are certain legal requirements
  48
  49         Before we can accept code contributions from you, we need a
  50         copyright assignment form filled out.
  51
  52         If you've developed some addition or patch to GDB that you
  53         would like to contribute, you should fill out a copyright
  54         assignment form and send it in to the FSF. We are unable to
  55         use code from you until this is on-file at the FSF, so get
  56         that paperwork in!  This form covers one batch of changes.
  57         Ref: http://gcc.gnu.org/fsf-forms/assignment-instructions.html
  58
  59         If you think you're going to be doing continuing work on GDB, it
  60         would be easier to use a different form, which arranges to
  61         assign the copyright for all your future changes to GDB. It is
  62         called assign.future. Please note that if you switch
  63         employers, the new employer will need to fill out the
  64         disclaim.future form; there is no need to fill out the
  65         assign.future form again.
  66         Ref: http://gcc.gnu.org/fsf-forms/assign.future
  67         Ref: http://gcc.gnu.org/fsf-forms/disclaim.future
  68
  69         There are several other forms you can fill out for different
  70         circumstances (e.g. to contribute an entirely new program, to
  71         contribute significant changes to a manual, etc.)
  72         Ref: http://gcc.gnu.org/fsf-forms/copyrights.html
  73
  74         Small changes can be accepted without a copyright assignment
  75         form on file.
  76
  77         This is pretty confusing! If you are unsure of what is
  78         necessary, just ask the GDB mailing list and we'll figure out
  79         what is best for you.
  80
  81         Note: Many of these forms have a place for "name of
  82         program". Insert the name of one program in that place -- in
  83         this case, "GDB".
  84
  85
  86 o       Submitting Patches
  87
  88         Every patch must have several pieces of information before we
  89         can properly evaluate it.
  90
  91         A description of the bug and how your patch fixes this
  92         bug. A reference to a testsuite failure is very helpful. For
  93         new features a description of the feature and your
  94         implementation.
  95
  96         A ChangeLog entry as plaintext (separate from the patch); see
  97         the various ChangeLog files for format and content. Note that,
  98         unlike some other projects, we do require ChangeLogs also for
  99         documentation (i.e., .texi files).
 100
 101         The patch itself. If you are accessing the CVS repository at:
 102         Cygnus, use "cvs update; cvs diff -c3p"; else, use "diff -c3p
 103         OLD NEW" or "diff -up OLD NEW". If your version of diff does
 104         not support these options, then get the latest version of GNU
 105         diff.
 106
 107         We accept patches as plain text (preferred for the compilers
 108         themselves), MIME attachments (preferred for the web pages),
 109         or as uuencoded gzipped text.
 110
 111         When you have all these pieces, bundle them up in a mail
 112         message and send it to gdb-patches@sourceware.cygnus.com. All
 113         patches and related discussion should be sent to the
 114         gdb-patches mailinglist. For further information on the GDB
 115         CVS repository, see the Anonymous read-only CVS access and
 116         Read-write CVS access page.
 117
 118 --
 119
 120 Supplemental information for GDB:
 121
 122 o       Please try to run the relevant testsuite before and after
 123         committing a patch
 124
 125         If the contributor doesn't do it then the maintainer will.  A
 126         contributor might include before/after test results in their
 127         contribution.
 128
 129
 130 o       For bug fixes, please try to include a way of
 131         demonstrating that the patch actually fixes something.
 132
 133         The best way of doing this is to ensure that the
 134         testsuite contains one or more test cases that
 135         fail without the fix but pass with the fix.
 136
 137         People are encouraged to submit patches that extend
 138         the testsuite.
 139
 140
 141 o       Please read your patch before submitting it.
 142
 143         A patch containing several unrelated changes or
 144         arbitrary reformats will be returned with a request
 145         to re-formatting / split it.
 146
 147
 148 o       If ``gdb/configure.in'' is modified then you don't
 149         need to include patches to the regenerated file
 150         ``configure''.
 151
 152         The maintainer will re-generate those files
 153         using autoconf (2.13 as of 2000-02-29).
 154
 155
 156 o       If ``gdb/gdbarch.sh'' is modified, you don't
 157         need to include patches to the generated files
 158         ``gdbarch.h'' and ``gdbarch.c''.
 159
 160         See ``gdb/configure.in'' above.