*** empty log message ***
[emacs.git] / CONTRIBUTE
blobd5d3b77d1426a9c18a3946cc9def2ecbaeb44b14
2                         Contributing to Emacs
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.
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.
17 You may also want to submit your change so that can be considered for
18 inclusion in a future version of Emacs (see below).
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.
25 Here are some style and legal conventions for contributors to Emacs:
28 * Coding Standards
30 Contributed code should follow the GNU Coding Standard.
32 If it doesn't, we'll need to find someone to fix the code before we
33 can use it.
35 Emacs has certain additional style and coding conventions.
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.
42 * Copyright Assignment
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.
49 Contact us at emacs-devel@gnu.org to obtain the relevant forms.
52 * Getting the Source Code
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.
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).
64 Ref: http://savannah.gnu.org/projects/emacs
67 * Submitting Patches
69 Every patch must have several pieces of information before we
70 can properly evaluate it.
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.
75 All subsequent discussion should also be sent to the mailing list.
77 ** Description
79 For bug fixes, a description of the bug and how your patch fixes this
80 bug.
82 For new features, a description of the feature and your
83 implementation.
85 ** ChangeLog
87 A ChangeLog entry as plaintext (separate from the patch).
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.
93 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
94 Manual, for how to write good log entries.
96 ** The patch itself.
98 Please use "Context Diff" format.
100 If you are accessing the CVS repository use
101         cvs update; cvs diff -cp
102 else, use
103         diff -cp OLD NEW
105 If your version of diff does not support these options, then get the
106 latest version of GNU Diff.
108 ** Mail format.
110 We prefer to get the patches as inline plain text.
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.
116 ** Please reread your patch before submitting it.
118 ** Do not mix changes.
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.
124 * Coding style and conventions.
126 ** Mandatory reading:
128 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
130 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
131 included in Emacs.
133 ** Remove all trailing whitespace in all source and text files.
135 ** Use ?\s instead of ?  in Lisp code for a space character.
138 * Supplemental information for Emacs Developers.
140 ** Write access to Emacs' CVS repository.
142 Once you become a frequent contributor to Emacs, we can consider
143 giving you write access to the CVS repository.
146 ** Emacs Mailing lists.
148 Discussion about Emacs development takes place on emacs-devel@gnu.org.
150 Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
152 Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
154 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
156 You can find the mailing lists archives at lists.gnu.org or gmane.org.
159 ** Document your changes.
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.
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.)
174 ** Understanding Emacs Internals.
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.
180 The file etc/DEBUG describes how to debug Emacs bugs.
184 * How to Maintain Copyright Years for GNU Emacs
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!).
191 ** For those files that have been added since then, we should add
192 the year it was added to Emacs, and all subsequent years.
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.
200 Local variables:
201 mode: outline
202 paragraph-separate: "[  \f]*$"
203 end: