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