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://www.gnu.org/software/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         Submissions which do not conform to the standards will be
  33         returned with a request to reformat the changes.
  34
  35         GDB has certain additional coding requirements.  Those
  36         requirements are explained in the GDB internals documentation
  37         in the gdb/doc directory.
  38
  39         Ref: http://www.gnu.org/prep/standards_toc.html
  40
  41
  42 o       Copyright Assignment
  43
  44         Before we can accept code contributions from you, we need a
  45         copyright assignment form filled out and filed with the FSF.
  46
  47         See some documentation by the FSF for details and contact us
  48         (either via the GDB mailing list or the GDB maintainer that is
  49         taking care of your contributions) to obtain the relevant
  50         forms.
  51
  52         Small changes can be accepted without a copyright assignment form
  53         on file.
  54
  55         Ref: http://www.gnu.org/prep/maintain.html#SEC6
  56
  57
  58 o       Submitting Patches
  59
  60         Every patch must have several pieces of information before we
  61         can properly evaluate it.
  62
  63         A description of the bug and how your patch fixes this
  64         bug. A reference to a testsuite failure is very helpful. For
  65         new features a description of the feature and your
  66         implementation.
  67
  68         A ChangeLog entry as plaintext (separate from the patch); see
  69         the various ChangeLog files for format and content. Note that,
  70         unlike some other projects, we do require ChangeLogs also for
  71         documentation (i.e., .texi files).
  72
  73         The patch itself.  If you are accessing the git repository, use
  74         "git diff", remembering first to update to the current master;
  75         else, use "diff -up OLD NEW". If your version of diff does not
  76         support these options, then get the latest version of GNU diff.
  77
  78         We accept patches as plain text (preferred for the compilers
  79         themselves), MIME attachments (preferred for the web pages),
  80         or as uuencoded gzipped text.
  81
  82         When you have all these pieces, bundle them up in a mail
  83         message and send it to gdb-patches@sourceware.org. All
  84         patches and related discussion should be sent to the
  85         gdb-patches mailinglist. For further information on the GDB
  86         git repository, see the Anonymous read-only git access and
  87         Read-write git access page.
  88
  89 --
  90
  91 Supplemental information for GDB:
  92
  93 o       Please try to run the relevant testsuite before and after
  94         committing a patch
  95
  96         If the contributor doesn't do it then the maintainer will.  A
  97         contributor might include before/after test results in their
  98         contribution.
  99
 100
 101 o       For bug fixes, please try to include a way of
 102         demonstrating that the patch actually fixes something.
 103
 104         The best way of doing this is to ensure that the
 105         testsuite contains one or more test cases that
 106         fail without the fix but pass with the fix.
 107
 108         People are encouraged to submit patches that extend
 109         the testsuite.
 110
 111
 112 o       Please read your patch before submitting it.
 113
 114         A patch containing several unrelated changes or
 115         arbitrary reformats will be returned with a request
 116         to re-formatting / split it.
 117
 118
 119 o       If ``gdb/configure.ac'' is modified then you don't
 120         need to include patches to the regenerated file
 121         ``configure''.
 122
 123         The maintainer will re-generate those files
 124         using autoconf (2.64 as of 2009-08-22).
 125
 126
 127 o       If ``gdb/gdbarch.sh'' is modified, you don't
 128         need to include patches to the generated files
 129         ``gdbarch.h'' and ``gdbarch.c''.
 130
 131         See ``gdb/configure.ac'' above.
 132
 133
 134 o       When submitting a patch that fixes a bug
 135         in GDB's bug database a brief reference
 136         to the bug can be included in the ChangeLog
 137         vis
 138
 139         * CONTRIBUTE: Mention PR convention.
 140         Fix PR gdb/4705.
 141
 142         The text ``PR gdb/4705'' should also be included
 143         in the git commit message.  That causes the
 144         patch to automatically be archived with the PR.