Commit | Line | Data |
---|---|---|
ba318903 | 1 | Copyright (C) 2006-2014 Free Software Foundation, Inc. |
ceaee230 JL |
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 | |
6d4cb47e GM |
25 | documentation, find and report bugs, check if existing bug reports |
26 | are fixed in newer versions of Emacs, contribute to the Emacs web | |
ceaee230 JL |
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 | ||
50e5ebca GM |
48 | The FSF (Free Software Foundation) is the copyright holder for GNU Emacs. |
49 | The FSF is a nonprofit with a worldwide mission to promote computer | |
50 | user freedom and to defend the rights of all free software users. | |
51 | For general information, see the website http://www.fsf.org/ . | |
52 | ||
53 | Generally speaking, for non-trivial contributions to GNU Emacs we | |
54 | require that the copyright be assigned to the FSF. For the reasons | |
55 | behind this, see: http://www.gnu.org/licenses/why-assign.html . | |
ceaee230 | 56 | |
84df8b96 GM |
57 | Copyright assignment is a simple process. Residents of some countries |
58 | can do it entirely electronically. We can help you get started, and | |
59 | answer any questions you may have (or point you to the people with the | |
60 | answers), at the emacs-devel@gnu.org mailing list. | |
e00a3e22 GM |
61 | |
62 | (Please note: general discussion about why some GNU projects ask | |
63 | for a copyright assignment is off-topic for emacs-devel. | |
64 | See gnu-misc-discuss instead.) | |
50e5ebca GM |
65 | |
66 | A copyright disclaimer is also a possibility, but we prefer an assignment. | |
510f531e GM |
67 | Note that the disclaimer, like an assignment, involves you sending |
68 | signed paperwork to the FSF (simply saying "this is in the public domain" | |
69 | is not enough). Also, a disclaimer cannot be applied to future work, it | |
70 | has to be repeated each time you want to send something new. | |
71 | ||
50e5ebca GM |
72 | We can accept small changes (roughly, fewer than 15 lines) without |
73 | an assignment. This is a cumulative limit (e.g. three separate 5 line | |
74 | patches) over all your contributions. | |
ceaee230 JL |
75 | |
76 | * Getting the Source Code | |
77 | ||
83a5f630 GM |
78 | The latest version of Emacs can be downloaded using Bazaar from the |
79 | Savannah web site. It is important to write your patch based on the | |
80 | latest version. If you start from an older version, your patch may be | |
81 | outdated (so that maintainers will have a hard time applying it), or | |
82 | changes in Emacs may have made your patch unnecessary. | |
ceaee230 | 83 | |
ac4c50ad ER |
84 | After you have downloaded the repository source, you should read the file |
85 | INSTALL.REPO for build instructions (they differ to some extent from a | |
ceaee230 JL |
86 | normal build). |
87 | ||
88 | Ref: http://savannah.gnu.org/projects/emacs | |
89 | ||
90 | ||
91 | * Submitting Patches | |
92 | ||
93 | Every patch must have several pieces of information before we | |
94 | can properly evaluate it. | |
95 | ||
96 | When you have all these pieces, bundle them up in a mail message and | |
14964899 GM |
97 | send it to the developers. Sending it to bug-gnu-emacs@gnu.org |
98 | (which is the bug/feature list) is recommended, because that list | |
99 | is coupled to a tracking system that makes it easier to locate patches. | |
100 | If your patch is not complete and you think it needs more discussion, | |
101 | you might want to send it to emacs-devel@gnu.org instead. If you | |
102 | revise your patch, send it as a followup to the initial topic. | |
ceaee230 JL |
103 | |
104 | ** Description | |
105 | ||
16af2326 | 106 | For bug fixes, a description of the bug and how your patch fixes it. |
ceaee230 | 107 | |
65b37d56 | 108 | For new features, a description of the feature and your implementation. |
ceaee230 JL |
109 | |
110 | ** ChangeLog | |
111 | ||
112 | A ChangeLog entry as plaintext (separate from the patch). | |
113 | ||
16af2326 | 114 | See the existing ChangeLog files for format and content. Note that, |
ceaee230 JL |
115 | unlike some other projects, we do require ChangeLogs also for |
116 | documentation, i.e. Texinfo files. | |
117 | ||
118 | Ref: "Change Log Concepts" node of the GNU Coding Standards Info | |
119 | Manual, for how to write good log entries. | |
120 | ||
121 | ** The patch itself. | |
122 | ||
83a5f630 GM |
123 | If you are accessing the Bazaar repository, make sure your copy is |
124 | up-to-date (e.g. with `bzr pull'), then use | |
125 | bzr diff --no-aliases --diff-options=-cp | |
126 | Else, use | |
ceaee230 JL |
127 | diff -cp OLD NEW |
128 | ||
ceaee230 JL |
129 | ** Mail format. |
130 | ||
16af2326 GM |
131 | We prefer to get the patches as plain text, either inline (be careful |
132 | your mail client does not change line breaks) or as MIME attachments. | |
ceaee230 JL |
133 | |
134 | ** Please reread your patch before submitting it. | |
135 | ||
136 | ** Do not mix changes. | |
137 | ||
138 | If you send several unrelated changes together, we will ask you to | |
139 | separate them so we can consider each of the changes by itself. | |
140 | ||
83a5f630 GM |
141 | ** Do not make formatting changes. |
142 | ||
143 | Making cosmetic formatting changes (indentation, etc) makes it harder | |
144 | to see what you have really changed. | |
145 | ||
ceaee230 JL |
146 | |
147 | * Coding style and conventions. | |
148 | ||
149 | ** Mandatory reading: | |
150 | ||
151 | The "Tips and Conventions" Appendix of the Emacs Lisp Reference. | |
152 | ||
153 | ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be | |
154 | included in Emacs. | |
155 | ||
156 | ** Remove all trailing whitespace in all source and text files. | |
157 | ||
158 | ** Use ?\s instead of ? in Lisp code for a space character. | |
159 | ||
160 | ||
161 | * Supplemental information for Emacs Developers. | |
162 | ||
83a5f630 | 163 | ** Write access to the Emacs repository. |
ceaee230 JL |
164 | |
165 | Once you become a frequent contributor to Emacs, we can consider | |
31466836 | 166 | giving you write access to the version-control repository. |
ceaee230 JL |
167 | |
168 | ||
169 | ** Emacs Mailing lists. | |
170 | ||
171 | Discussion about Emacs development takes place on emacs-devel@gnu.org. | |
172 | ||
14964899 GM |
173 | Bug reports and fixes, feature requests and implementations should be |
174 | sent to bug-gnu-emacs@gnu.org, the bug/feature list. This is coupled | |
175 | to the tracker at http://debbugs.gnu.org . | |
ceaee230 | 176 | |
14964899 GM |
177 | You can subscribe to the mailing lists, or see the list archives, |
178 | by following links from http://savannah.gnu.org/mail/?group=emacs . | |
ceaee230 JL |
179 | |
180 | ** Document your changes. | |
181 | ||
16af2326 | 182 | Any change that matters to end-users should have a NEWS entry. |
ceaee230 | 183 | |
16af2326 GM |
184 | Think about whether your change requires updating the documentation |
185 | (both manuals and doc-strings). If you know it does not, mark the NEWS | |
186 | entry with "---". If you know that *all* the necessary documentation | |
187 | updates have been made, mark the entry with "+++". Otherwise do not mark it. | |
ceaee230 JL |
188 | |
189 | ** Understanding Emacs Internals. | |
190 | ||
191 | The best way to understand Emacs Internals is to read the code, | |
192 | but the nodes "Tips" and "GNU Emacs Internals" in the Appendix | |
193 | of the Emacs Lisp Reference Manual may also help. | |
194 | ||
195 | The file etc/DEBUG describes how to debug Emacs bugs. | |
196 | ||
197 | ||
ceaee230 JL |
198 | \f |
199 | This file is part of GNU Emacs. | |
200 | ||
ab73e885 | 201 | GNU Emacs is free software: you can redistribute it and/or modify |
ceaee230 | 202 | it under the terms of the GNU General Public License as published by |
ab73e885 GM |
203 | the Free Software Foundation, either version 3 of the License, or |
204 | (at your option) any later version. | |
ceaee230 JL |
205 | |
206 | GNU Emacs is distributed in the hope that it will be useful, | |
207 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
208 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
209 | GNU General Public License for more details. | |
210 | ||
211 | You should have received a copy of the GNU General Public License | |
ab73e885 | 212 | along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
ceaee230 JL |
213 | \f |
214 | Local variables: | |
215 | mode: outline | |
216 | paragraph-separate: "[ \f]*$" | |
217 | end: | |
218 |