xref: /netbsd-src/external/gpl3/gdb/dist/gdb/CONTRIBUTE (revision b7b7574d3bf8eeb51a1fa3977b59142ec6434a55)
1
2			Contributing to GDB
3
4GDB is a collaborative project and one which wants to encourage new
5development.  You may wish to fix GDB bugs, improve testing, port GDB
6to a new platform, update documentation, add new GDB features, and the
7like. To help with this, there is a lot of documentation
8available.. In addition to the user guide and internals manual
9included in the GDB distribution, the GDB web pages also contain much
10information.
11
12You may also want to submit your change so that can be considered for
13conclusion in a future version of GDB (see below).  Regardless, we
14encourage you to distribute the change yourself.
15
16If you don't feel up to hacking GDB, there are still plenty of ways to
17help!  You can answer questions on the mailing lists, write
18documentation, find bugs, create a GDB related website (contribute to
19the official GDB web site), or create a GDB related software
20package. We welcome all of the above and feel free to ask on the GDB
21mailing lists if you are looking for feedback or for people to review
22a work in progress.
23
24Ref: http://www.gnu.org/software/gdb/
25
26Finally, there are certain legal requirements and style issues which
27all contributors need to be aware of.
28
29o	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
42o	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
58o	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
91Supplemental information for GDB:
92
93o	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
101o	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
112o	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
119o	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
127o	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
134o	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.
145