nt/config.nt: Sync with autogen/config.in.
[emacs.git] / etc / CONTRIBUTE
blobaff350f964283e794f1d722cdc9c07c95a0cef1f
1 Copyright (C) 2006-2012 Free Software Foundation, Inc.
2 See end for license conditions.
5                         Contributing to Emacs
7 Emacs is a collaborative project and we encourage contributions from
8 anyone and everyone.  If you want to contribute in the way that will
9 help us most, we recommend (1) fixing reported bugs and (2)
10 implementing the feature ideas in etc/TODO.  However, if you think of
11 new features to add, please suggest them too -- we might like your
12 idea.  Porting to new platforms is also useful, when there is a new
13 platform, but that is not common nowadays.
15 For documentation on how to develop Emacs changes, refer to the Emacs
16 Manual and the Emacs Lisp Reference Manual (both included in the Emacs
17 distribution).  The web pages in http://www.gnu.org/software/emacs
18 contain additional information.
20 You may also want to submit your change so that can be considered for
21 inclusion in a future version of Emacs (see below).
23 If you don't feel up to hacking Emacs, there are many other ways to
24 help.  You can answer questions on the mailing lists, write
25 documentation, find and report bugs, contribute to the Emacs web
26 pages, or develop a package that works with Emacs.
28 Here are some style and legal conventions for contributors to Emacs:
31 * Coding Standards
33 Contributed code should follow the GNU Coding Standards.
35 If it doesn't, we'll need to find someone to fix the code before we
36 can use it.
38 Emacs has certain additional style and coding conventions.
40 Ref: http://www.gnu.org/prep/standards/
41 Ref: GNU Coding Standards Info Manual
42 Ref: The "Tips" Appendix in the Emacs Lisp Reference.
45 * Copyright Assignment
47 The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
48 The FSF is a nonprofit with a worldwide mission to promote computer
49 user freedom and to defend the rights of all free software users.
50 For general information, see the website http://www.fsf.org/ .
52 Generally speaking, for non-trivial contributions to GNU Emacs we
53 require that the copyright be assigned to the FSF.  For the reasons
54 behind this, see: http://www.gnu.org/licenses/why-assign.html .
56 Copyright assignment is a simple process.  If you live in the US, you
57 can do it entirely electronically.  We can help you get started, and
58 answer any questions you may have (or point you to the people with the
59 answers), at the emacs-devel@gnu.org mailing list.
61 A copyright disclaimer is also a possibility, but we prefer an assignment.
62 We can accept small changes (roughly, fewer than 15 lines) without
63 an assignment.  This is a cumulative limit (e.g. three separate 5 line
64 patches) over all your contributions.
66 * Getting the Source Code
68 The latest version of Emacs can be downloaded using Bazaar from the
69 Savannah web site.  It is important to write your patch based on the
70 latest version.  If you start from an older version, your patch may be
71 outdated (so that maintainers will have a hard time applying it), or
72 changes in Emacs may have made your patch unnecessary.
74 After you have downloaded the Bazaar source, you should read the file
75 INSTALL.BZR for build instructions (they differ to some extent from a
76 normal build).
78 Ref: http://savannah.gnu.org/projects/emacs
81 * Submitting Patches
83 Every patch must have several pieces of information before we
84 can properly evaluate it.
86 When you have all these pieces, bundle them up in a mail message and
87 send it to the developers.  Sending it to bug-gnu-emacs@gnu.org
88 (which is the bug/feature list) is recommended, because that list
89 is coupled to a tracking system that makes it easier to locate patches.
90 If your patch is not complete and you think it needs more discussion,
91 you might want to send it to emacs-devel@gnu.org instead.  If you
92 revise your patch, send it as a followup to the initial topic.
94 ** Description
96 For bug fixes, a description of the bug and how your patch fixes this
97 bug.
99 For new features, a description of the feature and your implementation.
101 ** ChangeLog
103 A ChangeLog entry as plaintext (separate from the patch).
105 See the various ChangeLog files for format and content.  Note that,
106 unlike some other projects, we do require ChangeLogs also for
107 documentation, i.e. Texinfo files.
109 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
110 Manual, for how to write good log entries.
112 ** The patch itself.
114 Please use "Context Diff" format.
116 If you are accessing the Bazaar repository, make sure your copy is
117 up-to-date (e.g. with `bzr pull'), then use
118         bzr diff --no-aliases --diff-options=-cp
119 Else, use
120         diff -cp OLD NEW
122 If your version of diff does not support these options, then get the
123 latest version of GNU Diff.
125 ** Mail format.
127 We prefer to get the patches as inline plain text.
129 Please be aware of line wrapping which will make the patch unreadable
130 and useless for us.  To avoid that, you can use MIME attachments or,
131 as a last resort, uuencoded gzipped text.
133 ** Please reread your patch before submitting it.
135 ** Do not mix changes.
137 If you send several unrelated changes together, we will ask you to
138 separate them so we can consider each of the changes by itself.
140 ** Do not make formatting changes.
142 Making cosmetic formatting changes (indentation, etc) makes it harder
143 to see what you have really changed.
146 * Coding style and conventions.
148 ** Mandatory reading:
150 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
152 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
153 included in Emacs.
155 ** Remove all trailing whitespace in all source and text files.
157 ** Use ?\s instead of ?  in Lisp code for a space character.
160 * Supplemental information for Emacs Developers.
162 ** Write access to the Emacs repository.
164 Once you become a frequent contributor to Emacs, we can consider
165 giving you write access to the Bazaar repository.
168 ** Emacs Mailing lists.
170 Discussion about Emacs development takes place on emacs-devel@gnu.org.
172 Bug reports and fixes, feature requests and implementations should be
173 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
174 to the tracker at http://debbugs.gnu.org .
176 You can subscribe to the mailing lists, or see the list archives,
177 by following links from http://savannah.gnu.org/mail/?group=emacs .
179 ** Document your changes.
181 Think carefully about whether your change requires updating the
182 documentation.  If it does, you can either do this yourself or add an
183 item to the NEWS file.
185 If you document your change in NEWS, please mark the NEWS entry with
186 the documentation status of the change: if you submit the changes for
187 the manuals, mark it with "+++"; if it doesn't need to be documented,
188 mark it with "---"; if it needs to be documented, but you didn't
189 submit documentation changes, leave the NEWS entry unmarked.  (These
190 marks are checked by the Emacs maintainers to make sure every change
191 was reflected in the manuals.)
194 ** Understanding Emacs Internals.
196 The best way to understand Emacs Internals is to read the code,
197 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
198 of the Emacs Lisp Reference Manual may also help.
200 The file etc/DEBUG describes how to debug Emacs bugs.
204 This file is part of GNU Emacs.
206 GNU Emacs is free software: you can redistribute it and/or modify
207 it under the terms of the GNU General Public License as published by
208 the Free Software Foundation, either version 3 of the License, or
209 (at your option) any later version.
211 GNU Emacs is distributed in the hope that it will be useful,
212 but WITHOUT ANY WARRANTY; without even the implied warranty of
213 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
214 GNU General Public License for more details.
216 You should have received a copy of the GNU General Public License
217 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
219 Local variables:
220 mode: outline
221 paragraph-separate: "[  \f]*$"
222 end: