Merge from emacs--rel--22
[bpt/emacs.git] / CONTRIBUTE
CommitLineData
c2e309f2 1Copyright (C) 2006, 2007 Free Software Foundation, Inc.
7f6d64f8 2See end for license conditions.
c2e309f2 3
d1208b8b
NR
4
5 Contributing to Emacs
6
27e8e710
RS
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.
d1208b8b
NR
19
20You may also want to submit your change so that can be considered for
6f82a6d0 21inclusion in a future version of Emacs (see below).
d1208b8b 22
27e8e710
RS
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
25documentation, find and report bugs, contribute to the Emacs web
26pages, or develop a package that works with Emacs.
d1208b8b 27
27e8e710 28Here are some style and legal conventions for contributors to Emacs:
6f82a6d0 29
d1208b8b 30
05230057 31* Coding Standards
d1208b8b 32
05230057 33Contributed code should follow the GNU Coding Standard.
d1208b8b 34
05230057
KS
35If it doesn't, we'll need to find someone to fix the code before we
36can use it.
d1208b8b 37
05230057 38Emacs has certain additional style and coding conventions.
d1208b8b 39
05230057
KS
40Ref: http://www.gnu.org/prep/standards_toc.html
41Ref: GNU Coding Standards Info Manual
42Ref: The "Tips" Appendix in the Emacs Lisp Reference.
d1208b8b 43
d1208b8b 44
05230057 45* Copyright Assignment
d1208b8b 46
05230057
KS
47We can accept small changes without legal papers, and for medium-size
48changes a copyright disclaimer is ok too. To accept substantial
49contributions from you, we need a copyright assignment form filled out
50and filed with the FSF.
d1208b8b 51
05230057 52Contact us at emacs-devel@gnu.org to obtain the relevant forms.
d1208b8b 53
d1208b8b 54
05230057 55* Getting the Source Code
ccda8b92 56
05230057
KS
57The latest version of Emacs can be downloaded using CVS or Arch from
58the Savannah web site. It is important to write your patch based on
59this version; if you start from an older version, your patch may be
60outdated when you write it, and maintainers will have hard time
61applying it.
ccda8b92 62
05230057
KS
63After you have downloaded the CVS source, you should read the file
64INSTALL.CVS for build instructions (they differ to some extent from a
65normal build).
d1208b8b 66
05230057 67Ref: http://savannah.gnu.org/projects/emacs
d1208b8b 68
d1208b8b 69
05230057 70* Submitting Patches
d1208b8b 71
05230057
KS
72Every patch must have several pieces of information before we
73can properly evaluate it.
d1208b8b 74
05230057
KS
75When you have all these pieces, bundle them up in a mail message and
76send it to emacs-pretest-bug@gnu.org or emacs-devel@gnu.org.
d1208b8b 77
05230057 78All subsequent discussion should also be sent to the mailing list.
6f82a6d0 79
05230057 80** Description
d1208b8b 81
05230057
KS
82For bug fixes, a description of the bug and how your patch fixes this
83bug.
d1208b8b 84
05230057
KS
85For new features, a description of the feature and your
86implementation.
d1208b8b 87
05230057 88** ChangeLog
d1208b8b 89
05230057 90A ChangeLog entry as plaintext (separate from the patch).
d1208b8b 91
05230057
KS
92See the various ChangeLog files for format and content. Note that,
93unlike some other projects, we do require ChangeLogs also for
94documentation, i.e. Texinfo files.
27e8e710 95
05230057
KS
96Ref: "Change Log Concepts" node of the GNU Coding Standards Info
97Manual, for how to write good log entries.
d1208b8b 98
05230057 99** The patch itself.
ccda8b92 100
05230057 101Please use "Context Diff" format.
d1208b8b 102
05230057
KS
103If you are accessing the CVS repository use
104 cvs update; cvs diff -cp
105else, use
106 diff -cp OLD NEW
d1208b8b 107
05230057
KS
108If your version of diff does not support these options, then get the
109latest version of GNU Diff.
ccda8b92 110
05230057 111** Mail format.
d1208b8b 112
05230057 113We prefer to get the patches as inline plain text.
d1208b8b 114
05230057
KS
115Please be aware of line wrapping which will make the patch unreadable
116and useless for us. To avoid that, you can use MIME attachments or,
117as a last resort, uuencoded gzipped text.
014a250c 118
05230057 119** Please reread your patch before submitting it.
d1208b8b 120
05230057
KS
121** Do not mix changes.
122
123If you send several unrelated changes together, we will ask you to
124separate them so we can consider each of the changes by itself.
125
126
127* Coding style and conventions.
128
129** Mandatory reading:
130
131The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
132
133** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
134included in Emacs.
135
136** Remove all trailing whitespace in all source and text files.
137
138** Use ?\s instead of ? in Lisp code for a space character.
139
140
141* Supplemental information for Emacs Developers.
142
143** Write access to Emacs' CVS repository.
144
145Once you become a frequent contributor to Emacs, we can consider
146giving you write access to the CVS repository.
147
148
149** Emacs Mailing lists.
150
151Discussion about Emacs development takes place on emacs-devel@gnu.org.
152
f41adf50 153Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
05230057
KS
154
155Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
156
157You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
158
f41adf50 159You can find the mailing lists archives at lists.gnu.org or gmane.org.
05230057
KS
160
161
162** Document your changes.
163
164Think carefully about whether your change requires updating the
165documentation. If it does, you can either do this yourself or add an
166item to the NEWS file.
167
168If you document your change in NEWS, please mark the NEWS entry with
169the documentation status of the change: if you submit the changes for
170the manuals, mark it with "+++"; if it doesn't need to be documented,
171mark it with "---"; if it needs to be documented, but you didn't
172submit documentation changes, leave the NEWS entry unmarked. (These
173marks are checked by the Emacs maintainers to make sure every change
174was reflected in the manuals.)
175
176
177** Understanding Emacs Internals.
178
179The best way to understand Emacs Internals is to read the code,
180but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
181of the Emacs Lisp Reference Manual may also help.
182
183The file etc/DEBUG describes how to debug Emacs bugs.
184
185
186
187* How to Maintain Copyright Years for GNU Emacs
188
7f6d64f8
GM
189See admin/notes/copyright.
190
05230057
KS
191** Our lawyer says it is ok if we add, to each file that has been in Emacs
192since Emacs 21 came out in 2001, all the subsequent years. We don't
193need to check whether *that file* was changed in those years.
194It's sufficient that *Emacs* was changed in those years (and it was!).
195
196** For those files that have been added since then, we should add
f41adf50 197the year it was added to Emacs, and all subsequent years.
05230057
KS
198
199** For the refcards under etc/, it's ok to simply use the latest year
200(typically in a `\def\year{YEAR}' expression) for the rendered copyright
201notice, while maintaining the full list of years in the copyright notice
202in the comments.
203
7f6d64f8
GM
204
205\f
206This file is part of GNU Emacs.
207
208GNU Emacs is free software; you can redistribute it and/or modify
209it under the terms of the GNU General Public License as published by
210the Free Software Foundation; either version 2, or (at your option)
211any later version.
212
213GNU Emacs is distributed in the hope that it will be useful,
214but WITHOUT ANY WARRANTY; without even the implied warranty of
215MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
216GNU General Public License for more details.
217
218You should have received a copy of the GNU General Public License
219along with GNU Emacs; see the file COPYING. If not, write to the
220Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
221Boston, MA 02110-1301, USA.
05230057
KS
222\f
223Local variables:
224mode: outline
225paragraph-separate: "[ \f]*$"
226end:
d1208b8b 227