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