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