| 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 CVS repository use |
| 74 | "cvs update; cvs diff -cp"; else, use "diff -cp OLD NEW" or |
| 75 | "diff -up OLD NEW". If your version of diff does not support |
| 76 | 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 | CVS repository, see the Anonymous read-only CVS access and |
| 87 | Read-write CVS 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.59 as of 2005-01-07). |
| 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 CVS commit message. That causes the |
| 144 | patch to automatically be archived with the PR. |