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