declare smobs in alloc.c
[bpt/emacs.git] / etc / CONTRIBUTE
CommitLineData
ba318903 1Copyright (C) 2006-2014 Free Software Foundation, Inc.
ceaee230
JL
2See end for license conditions.
3
4
5 Contributing to Emacs
6
7Emacs is a collaborative project and we encourage contributions from
8anyone and everyone. If you want to contribute in the way that will
9help us most, we recommend (1) fixing reported bugs and (2)
10implementing the feature ideas in etc/TODO. However, if you think of
11new features to add, please suggest them too -- we might like your
12idea. Porting to new platforms is also useful, when there is a new
13platform, but that is not common nowadays.
14
15For documentation on how to develop Emacs changes, refer to the Emacs
16Manual and the Emacs Lisp Reference Manual (both included in the Emacs
17distribution). The web pages in http://www.gnu.org/software/emacs
18contain additional information.
19
20You may also want to submit your change so that can be considered for
21inclusion in a future version of Emacs (see below).
22
23If you don't feel up to hacking Emacs, there are many other ways to
24help. You can answer questions on the mailing lists, write
6d4cb47e
GM
25documentation, find and report bugs, check if existing bug reports
26are fixed in newer versions of Emacs, contribute to the Emacs web
ceaee230
JL
27pages, or develop a package that works with Emacs.
28
29Here are some style and legal conventions for contributors to Emacs:
30
31
32* Coding Standards
33
83a5f630 34Contributed code should follow the GNU Coding Standards.
ceaee230
JL
35
36If it doesn't, we'll need to find someone to fix the code before we
37can use it.
38
39Emacs has certain additional style and coding conventions.
40
d40084d1 41Ref: http://www.gnu.org/prep/standards/
ceaee230
JL
42Ref: GNU Coding Standards Info Manual
43Ref: The "Tips" Appendix in the Emacs Lisp Reference.
44
45
46* Copyright Assignment
47
50e5ebca
GM
48The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
49The FSF is a nonprofit with a worldwide mission to promote computer
50user freedom and to defend the rights of all free software users.
51For general information, see the website http://www.fsf.org/ .
52
53Generally speaking, for non-trivial contributions to GNU Emacs we
54require that the copyright be assigned to the FSF. For the reasons
55behind this, see: http://www.gnu.org/licenses/why-assign.html .
ceaee230 56
84df8b96
GM
57Copyright assignment is a simple process. Residents of some countries
58can do it entirely electronically. We can help you get started, and
59answer any questions you may have (or point you to the people with the
60answers), at the emacs-devel@gnu.org mailing list.
e00a3e22
GM
61
62(Please note: general discussion about why some GNU projects ask
63for a copyright assignment is off-topic for emacs-devel.
64See gnu-misc-discuss instead.)
50e5ebca
GM
65
66A copyright disclaimer is also a possibility, but we prefer an assignment.
510f531e
GM
67Note that the disclaimer, like an assignment, involves you sending
68signed paperwork to the FSF (simply saying "this is in the public domain"
69is not enough). Also, a disclaimer cannot be applied to future work, it
70has to be repeated each time you want to send something new.
71
50e5ebca
GM
72We can accept small changes (roughly, fewer than 15 lines) without
73an assignment. This is a cumulative limit (e.g. three separate 5 line
74patches) over all your contributions.
ceaee230
JL
75
76* Getting the Source Code
77
83a5f630
GM
78The latest version of Emacs can be downloaded using Bazaar from the
79Savannah web site. It is important to write your patch based on the
80latest version. If you start from an older version, your patch may be
81outdated (so that maintainers will have a hard time applying it), or
82changes in Emacs may have made your patch unnecessary.
ceaee230 83
ac4c50ad
ER
84After you have downloaded the repository source, you should read the file
85INSTALL.REPO for build instructions (they differ to some extent from a
ceaee230
JL
86normal build).
87
88Ref: http://savannah.gnu.org/projects/emacs
89
90
91* Submitting Patches
92
93Every patch must have several pieces of information before we
94can properly evaluate it.
95
96When you have all these pieces, bundle them up in a mail message and
14964899
GM
97send it to the developers. Sending it to bug-gnu-emacs@gnu.org
98(which is the bug/feature list) is recommended, because that list
99is coupled to a tracking system that makes it easier to locate patches.
100If your patch is not complete and you think it needs more discussion,
101you might want to send it to emacs-devel@gnu.org instead. If you
102revise your patch, send it as a followup to the initial topic.
ceaee230
JL
103
104** Description
105
16af2326 106For bug fixes, a description of the bug and how your patch fixes it.
ceaee230 107
65b37d56 108For new features, a description of the feature and your implementation.
ceaee230
JL
109
110** ChangeLog
111
112A ChangeLog entry as plaintext (separate from the patch).
113
16af2326 114See the existing ChangeLog files for format and content. Note that,
ceaee230
JL
115unlike some other projects, we do require ChangeLogs also for
116documentation, i.e. Texinfo files.
117
118Ref: "Change Log Concepts" node of the GNU Coding Standards Info
119Manual, for how to write good log entries.
120
121** The patch itself.
122
83a5f630
GM
123If you are accessing the Bazaar repository, make sure your copy is
124up-to-date (e.g. with `bzr pull'), then use
125 bzr diff --no-aliases --diff-options=-cp
126Else, use
ceaee230
JL
127 diff -cp OLD NEW
128
ceaee230
JL
129** Mail format.
130
16af2326
GM
131We prefer to get the patches as plain text, either inline (be careful
132your mail client does not change line breaks) or as MIME attachments.
ceaee230
JL
133
134** Please reread your patch before submitting it.
135
136** Do not mix changes.
137
138If you send several unrelated changes together, we will ask you to
139separate them so we can consider each of the changes by itself.
140
83a5f630
GM
141** Do not make formatting changes.
142
143Making cosmetic formatting changes (indentation, etc) makes it harder
144to see what you have really changed.
145
ceaee230
JL
146
147* Coding style and conventions.
148
149** Mandatory reading:
150
151The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
152
153** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
154included in Emacs.
155
156** Remove all trailing whitespace in all source and text files.
157
158** Use ?\s instead of ? in Lisp code for a space character.
159
160
161* Supplemental information for Emacs Developers.
162
83a5f630 163** Write access to the Emacs repository.
ceaee230
JL
164
165Once you become a frequent contributor to Emacs, we can consider
31466836 166giving you write access to the version-control repository.
ceaee230
JL
167
168
169** Emacs Mailing lists.
170
171Discussion about Emacs development takes place on emacs-devel@gnu.org.
172
14964899
GM
173Bug reports and fixes, feature requests and implementations should be
174sent to bug-gnu-emacs@gnu.org, the bug/feature list. This is coupled
175to the tracker at http://debbugs.gnu.org .
ceaee230 176
14964899
GM
177You can subscribe to the mailing lists, or see the list archives,
178by following links from http://savannah.gnu.org/mail/?group=emacs .
ceaee230
JL
179
180** Document your changes.
181
16af2326 182Any change that matters to end-users should have a NEWS entry.
ceaee230 183
16af2326
GM
184Think about whether your change requires updating the documentation
185(both manuals and doc-strings). If you know it does not, mark the NEWS
186entry with "---". If you know that *all* the necessary documentation
187updates have been made, mark the entry with "+++". Otherwise do not mark it.
ceaee230
JL
188
189** Understanding Emacs Internals.
190
191The best way to understand Emacs Internals is to read the code,
192but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
193of the Emacs Lisp Reference Manual may also help.
194
195The file etc/DEBUG describes how to debug Emacs bugs.
196
197
ceaee230
JL
198\f
199This file is part of GNU Emacs.
200
ab73e885 201GNU Emacs is free software: you can redistribute it and/or modify
ceaee230 202it under the terms of the GNU General Public License as published by
ab73e885
GM
203the Free Software Foundation, either version 3 of the License, or
204(at your option) any later version.
ceaee230
JL
205
206GNU Emacs is distributed in the hope that it will be useful,
207but WITHOUT ANY WARRANTY; without even the implied warranty of
208MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
209GNU General Public License for more details.
210
211You should have received a copy of the GNU General Public License
ab73e885 212along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
ceaee230
JL
213\f
214Local variables:
215mode: outline
216paragraph-separate: "[ \f]*$"
217end:
218