Commit | Line | Data |
---|---|---|
83a5f630 GM |
1 | Copyright (C) 2006, 2007, 2008, 2009, 2010 |
2 | Free Software Foundation, Inc. | |
ceaee230 JL |
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 | ||
83a5f630 | 34 | Contributed code should follow the GNU Coding Standards. |
ceaee230 JL |
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 | ||
d40084d1 | 41 | Ref: http://www.gnu.org/prep/standards/ |
ceaee230 JL |
42 | Ref: GNU Coding Standards Info Manual |
43 | Ref: The "Tips" Appendix in the Emacs Lisp Reference. | |
44 | ||
45 | ||
46 | * Copyright Assignment | |
47 | ||
83a5f630 GM |
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. | |
ceaee230 JL |
54 | |
55 | ||
56 | * Getting the Source Code | |
57 | ||
83a5f630 GM |
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. | |
ceaee230 | 63 | |
83a5f630 GM |
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 | |
ceaee230 JL |
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 | |
893db5bc | 77 | send it to bug-gnu-emacs@gnu.org or emacs-devel@gnu.org. |
ceaee230 | 78 | |
83a5f630 | 79 | All subsequent discussion should be sent to the same mailing list. |
ceaee230 JL |
80 | |
81 | ** Description | |
82 | ||
83 | For bug fixes, a description of the bug and how your patch fixes this | |
84 | bug. | |
85 | ||
65b37d56 | 86 | For new features, a description of the feature and your implementation. |
ceaee230 JL |
87 | |
88 | ** ChangeLog | |
89 | ||
90 | A ChangeLog entry as plaintext (separate from the patch). | |
91 | ||
83a5f630 | 92 | See the various ChangeLog files for format and content. Note that, |
ceaee230 JL |
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 | ||
83a5f630 GM |
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 | |
ceaee230 JL |
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 | ||
83a5f630 GM |
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 | ||
ceaee230 JL |
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 | ||
83a5f630 | 149 | ** Write access to the Emacs repository. |
ceaee230 JL |
150 | |
151 | Once you become a frequent contributor to Emacs, we can consider | |
83a5f630 | 152 | giving you write access to the Bazaar repository. |
ceaee230 JL |
153 | |
154 | ||
155 | ** Emacs Mailing lists. | |
156 | ||
157 | Discussion about Emacs development takes place on emacs-devel@gnu.org. | |
158 | ||
83a5f630 | 159 | Bug reports and feature requests are sent to bug-gnu-emacs@gnu.org. |
ceaee230 JL |
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 | ||
ceaee230 JL |
190 | \f |
191 | This file is part of GNU Emacs. | |
192 | ||
ab73e885 | 193 | GNU Emacs is free software: you can redistribute it and/or modify |
ceaee230 | 194 | it under the terms of the GNU General Public License as published by |
ab73e885 GM |
195 | the Free Software Foundation, either version 3 of the License, or |
196 | (at your option) any later version. | |
ceaee230 JL |
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 | |
ab73e885 | 204 | along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
ceaee230 JL |
205 | \f |
206 | Local variables: | |
207 | mode: outline | |
208 | paragraph-separate: "[ \f]*$" | |
209 | end: | |
210 |