107178
|
1 Copyright (C) 2006, 2007, 2008, 2009, 2010
|
|
2 Free Software Foundation, Inc.
|
84410
|
3 See end for license conditions.
|
|
4
|
|
5
|
|
6 Contributing to Emacs
|
|
7
|
|
8 Emacs is a collaborative project and we encourage contributions from
|
|
9 anyone and everyone. If you want to contribute in the way that will
|
|
10 help us most, we recommend (1) fixing reported bugs and (2)
|
|
11 implementing the feature ideas in etc/TODO. However, if you think of
|
|
12 new features to add, please suggest them too -- we might like your
|
|
13 idea. Porting to new platforms is also useful, when there is a new
|
|
14 platform, but that is not common nowadays.
|
|
15
|
|
16 For documentation on how to develop Emacs changes, refer to the Emacs
|
|
17 Manual and the Emacs Lisp Reference Manual (both included in the Emacs
|
|
18 distribution). The web pages in http://www.gnu.org/software/emacs
|
|
19 contain additional information.
|
|
20
|
|
21 You may also want to submit your change so that can be considered for
|
|
22 inclusion in a future version of Emacs (see below).
|
|
23
|
|
24 If you don't feel up to hacking Emacs, there are many other ways to
|
|
25 help. You can answer questions on the mailing lists, write
|
|
26 documentation, find and report bugs, contribute to the Emacs web
|
|
27 pages, or develop a package that works with Emacs.
|
|
28
|
|
29 Here are some style and legal conventions for contributors to Emacs:
|
|
30
|
|
31
|
|
32 * Coding Standards
|
|
33
|
107178
|
34 Contributed code should follow the GNU Coding Standards.
|
84410
|
35
|
|
36 If it doesn't, we'll need to find someone to fix the code before we
|
|
37 can use it.
|
|
38
|
|
39 Emacs has certain additional style and coding conventions.
|
|
40
|
106592
|
41 Ref: http://www.gnu.org/prep/standards/
|
84410
|
42 Ref: GNU Coding Standards Info Manual
|
|
43 Ref: The "Tips" Appendix in the Emacs Lisp Reference.
|
|
44
|
|
45
|
|
46 * Copyright Assignment
|
|
47
|
107178
|
48 We can accept small changes (roughly, fewer than 15 lines) without
|
|
49 legal papers. Anything more substantial requires a copyright
|
|
50 disclaimer or assignment (the latter is preferred, especially for
|
|
51 larger changes). Both of these involved filling out a short form and
|
|
52 filing it with the FSF. The process is straightforward -- contact us
|
|
53 at emacs-devel@gnu.org to obtain the relevant forms.
|
84410
|
54
|
|
55
|
|
56 * Getting the Source Code
|
|
57
|
107178
|
58 The latest version of Emacs can be downloaded using Bazaar from the
|
|
59 Savannah web site. It is important to write your patch based on the
|
|
60 latest version. If you start from an older version, your patch may be
|
|
61 outdated (so that maintainers will have a hard time applying it), or
|
|
62 changes in Emacs may have made your patch unnecessary.
|
84410
|
63
|
107178
|
64 After you have downloaded the Bazaar source, you should read the file
|
|
65 INSTALL.BZR for build instructions (they differ to some extent from a
|
84410
|
66 normal build).
|
|
67
|
|
68 Ref: http://savannah.gnu.org/projects/emacs
|
|
69
|
|
70
|
|
71 * Submitting Patches
|
|
72
|
|
73 Every patch must have several pieces of information before we
|
|
74 can properly evaluate it.
|
|
75
|
|
76 When you have all these pieces, bundle them up in a mail message and
|
106802
|
77 send it to bug-gnu-emacs@gnu.org or emacs-devel@gnu.org.
|
84410
|
78
|
107178
|
79 All subsequent discussion should be sent to the same mailing list.
|
84410
|
80
|
|
81 ** Description
|
|
82
|
|
83 For bug fixes, a description of the bug and how your patch fixes this
|
|
84 bug.
|
|
85
|
84844
|
86 For new features, a description of the feature and your implementation.
|
84410
|
87
|
|
88 ** ChangeLog
|
|
89
|
|
90 A ChangeLog entry as plaintext (separate from the patch).
|
|
91
|
107178
|
92 See the various ChangeLog files for format and content. Note that,
|
84410
|
93 unlike some other projects, we do require ChangeLogs also for
|
|
94 documentation, i.e. Texinfo files.
|
|
95
|
|
96 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
|
|
97 Manual, for how to write good log entries.
|
|
98
|
|
99 ** The patch itself.
|
|
100
|
|
101 Please use "Context Diff" format.
|
|
102
|
107178
|
103 If you are accessing the Bazaar repository, make sure your copy is
|
|
104 up-to-date (e.g. with `bzr pull'), then use
|
|
105 bzr diff --no-aliases --diff-options=-cp
|
|
106 Else, use
|
84410
|
107 diff -cp OLD NEW
|
|
108
|
|
109 If your version of diff does not support these options, then get the
|
|
110 latest version of GNU Diff.
|
|
111
|
|
112 ** Mail format.
|
|
113
|
|
114 We prefer to get the patches as inline plain text.
|
|
115
|
|
116 Please be aware of line wrapping which will make the patch unreadable
|
|
117 and useless for us. To avoid that, you can use MIME attachments or,
|
|
118 as a last resort, uuencoded gzipped text.
|
|
119
|
|
120 ** Please reread your patch before submitting it.
|
|
121
|
|
122 ** Do not mix changes.
|
|
123
|
|
124 If you send several unrelated changes together, we will ask you to
|
|
125 separate them so we can consider each of the changes by itself.
|
|
126
|
107178
|
127 ** Do not make formatting changes.
|
|
128
|
|
129 Making cosmetic formatting changes (indentation, etc) makes it harder
|
|
130 to see what you have really changed.
|
|
131
|
84410
|
132
|
|
133 * Coding style and conventions.
|
|
134
|
|
135 ** Mandatory reading:
|
|
136
|
|
137 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
|
|
138
|
|
139 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
|
|
140 included in Emacs.
|
|
141
|
|
142 ** Remove all trailing whitespace in all source and text files.
|
|
143
|
|
144 ** Use ?\s instead of ? in Lisp code for a space character.
|
|
145
|
|
146
|
|
147 * Supplemental information for Emacs Developers.
|
|
148
|
107178
|
149 ** Write access to the Emacs repository.
|
84410
|
150
|
|
151 Once you become a frequent contributor to Emacs, we can consider
|
107178
|
152 giving you write access to the Bazaar repository.
|
84410
|
153
|
|
154
|
|
155 ** Emacs Mailing lists.
|
|
156
|
|
157 Discussion about Emacs development takes place on emacs-devel@gnu.org.
|
|
158
|
107178
|
159 Bug reports and feature requests are sent to bug-gnu-emacs@gnu.org.
|
84410
|
160
|
|
161 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
|
|
162
|
|
163 You can find the mailing lists archives at lists.gnu.org or gmane.org.
|
|
164
|
|
165
|
|
166 ** Document your changes.
|
|
167
|
|
168 Think carefully about whether your change requires updating the
|
|
169 documentation. If it does, you can either do this yourself or add an
|
|
170 item to the NEWS file.
|
|
171
|
|
172 If you document your change in NEWS, please mark the NEWS entry with
|
|
173 the documentation status of the change: if you submit the changes for
|
|
174 the manuals, mark it with "+++"; if it doesn't need to be documented,
|
|
175 mark it with "---"; if it needs to be documented, but you didn't
|
|
176 submit documentation changes, leave the NEWS entry unmarked. (These
|
|
177 marks are checked by the Emacs maintainers to make sure every change
|
|
178 was reflected in the manuals.)
|
|
179
|
|
180
|
|
181 ** Understanding Emacs Internals.
|
|
182
|
|
183 The best way to understand Emacs Internals is to read the code,
|
|
184 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
|
|
185 of the Emacs Lisp Reference Manual may also help.
|
|
186
|
|
187 The file etc/DEBUG describes how to debug Emacs bugs.
|
|
188
|
|
189
|
|
190
|
|
191 This file is part of GNU Emacs.
|
|
192
|
95004
|
193 GNU Emacs is free software: you can redistribute it and/or modify
|
84410
|
194 it under the terms of the GNU General Public License as published by
|
95004
|
195 the Free Software Foundation, either version 3 of the License, or
|
|
196 (at your option) any later version.
|
84410
|
197
|
|
198 GNU Emacs is distributed in the hope that it will be useful,
|
|
199 but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
200 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
201 GNU General Public License for more details.
|
|
202
|
|
203 You should have received a copy of the GNU General Public License
|
95004
|
204 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
|
84410
|
205
|
|
206 Local variables:
|
|
207 mode: outline
|
|
208 paragraph-separate: "[ ]*$"
|
|
209 end:
|
|
210
|