Commit | Line | Data |
---|---|---|
d1208b8b NR |
1 | |
2 | Contributing to Emacs | |
3 | ||
27e8e710 RS |
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. | |
d1208b8b NR |
16 | |
17 | You may also want to submit your change so that can be considered for | |
6f82a6d0 | 18 | inclusion in a future version of Emacs (see below). |
d1208b8b | 19 | |
27e8e710 RS |
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. | |
d1208b8b | 24 | |
27e8e710 | 25 | Here are some style and legal conventions for contributors to Emacs: |
6f82a6d0 | 26 | |
d1208b8b NR |
27 | |
28 | o Coding Standards | |
29 | ||
27e8e710 RS |
30 | Contributed code should follow the GNU Coding Standard. |
31 | If it doesn't, we'll need to find someone to fix the code | |
32 | before we can use it. | |
d1208b8b | 33 | |
27e8e710 | 34 | Emacs has certain additional style and coding conventions. |
d1208b8b NR |
35 | |
36 | Ref: http://www.gnu.org/prep/standards_toc.html | |
014a250c | 37 | Ref: GNU Coding Standards Info Manual |
d1208b8b NR |
38 | |
39 | ||
40 | o Copyright Assignment | |
41 | ||
27e8e710 | 42 | We can accept small changes without legal papers, and for |
014a250c | 43 | medium-size changes a copyright disclaimer is ok too. To |
27e8e710 RS |
44 | accept substantial contributions from you, we need a copyright |
45 | assignment form filled out and filed with the FSF. | |
d1208b8b | 46 | |
27e8e710 | 47 | Contact us at emacs-devel@gnu.org to obtain the relevant |
d1208b8b NR |
48 | forms. |
49 | ||
d1208b8b NR |
50 | |
51 | o Getting the Source Code | |
52 | ||
27e8e710 RS |
53 | The latest version of Emacs can be downloaded using CVS or |
54 | Arch from the Savannah web site. It is important to write | |
014a250c EZ |
55 | your patch based on this version; if you start from an older |
56 | version, your patch may be outdated when you write it, and | |
57 | maintainers will have hard time applying it. | |
ccda8b92 | 58 | |
014a250c EZ |
59 | After you have downloaded the CVS source, you should read the |
60 | file INSTALL.CVS for build instructions (they differ to some | |
61 | extent from a normal build). | |
ccda8b92 | 62 | |
d1208b8b NR |
63 | Ref: http://savannah.gnu.org/projects/emacs |
64 | ||
65 | ||
66 | o Submitting Patches | |
67 | ||
68 | Every patch must have several pieces of information before we | |
69 | can properly evaluate it. | |
70 | ||
014a250c EZ |
71 | * For bug fixes, a description of the bug and how your patch |
72 | fixes this bug. | |
d1208b8b | 73 | |
014a250c EZ |
74 | * For new features, a description of the feature and your |
75 | implementation. | |
d1208b8b | 76 | |
014a250c EZ |
77 | * A ChangeLog entry as plaintext (separate from the patch); |
78 | see the various ChangeLog files for format and content. Note | |
79 | that, unlike some other projects, we do require ChangeLogs | |
80 | also for documentation, i.e. Texinfo files. | |
6f82a6d0 | 81 | |
014a250c EZ |
82 | Ref: "Change Log Concepts" node of the GNU Coding Standards |
83 | Info Manual, for how to write good log entries. | |
d1208b8b | 84 | |
014a250c EZ |
85 | * The patch itself. If you are accessing the CVS repository |
86 | use "cvs update; cvs diff -cp"; else, use "diff -cp OLD NEW". | |
87 | If your version of diff does not support these options, then | |
88 | get the latest version of GNU Diff. | |
d1208b8b | 89 | |
014a250c EZ |
90 | * We accept the patches as plain text (preferred for the |
91 | compilers themselves), MIME attachments (preferred for the | |
92 | web pages), or as uuencoded gzipped text. | |
d1208b8b NR |
93 | |
94 | When you have all these pieces, bundle them up in a mail message | |
95 | and send it to emacs-pretest-bug@gnu.org or emacs-devel@gnu.org. | |
6f82a6d0 NR |
96 | All subsequent discussion should also be sent to the mailing |
97 | list. | |
d1208b8b NR |
98 | |
99 | ||
27e8e710 RS |
100 | o Please reread your patch before submitting it. |
101 | ||
d1208b8b | 102 | |
27e8e710 RS |
103 | o If you send several unrelated changes together, we will |
104 | ask you to separate them so we can consider each of the changes | |
105 | by itself. | |
ccda8b92 | 106 | |
d1208b8b NR |
107 | |
108 | o Supplemental information for Emacs Developers: | |
109 | ||
27e8e710 RS |
110 | Once you become a frequent contributor to Emacs, we can |
111 | consider giving you write access to the CVS repository. | |
ccda8b92 | 112 | |
d1208b8b NR |
113 | Discussion about Emacs development takes place on |
114 | emacs-devel@gnu.org. | |
115 | ||
116 | Think carefully about whether your change requires updating the | |
117 | documentation. If it does, you can either do this yourself or | |
118 | add an item to the NEWS file. | |
119 | ||
014a250c EZ |
120 | If you document your change in NEWS, please mark the NEWS |
121 | entry with the documentation status of the change: if you | |
122 | submit the changes for the manuals, mark it with "+++"; if it | |
123 | doesn't need to be documented, mark it with "---"; if it needs | |
124 | to be documented, but you didn't submit documentation changes, | |
125 | leave the NEWS entry unmarked. (These marks are checked by | |
126 | the Emacs maintainers to make sure every change was reflected | |
127 | in the manuals.) | |
128 | ||
129 | The best way to understand Emacs Internals is to read the code, | |
130 | but the nodes "Tips" and "GNU Emacs Internals" in the Appendix | |
6f82a6d0 | 131 | of the Emacs Lisp Reference Manual may also help. |
d1208b8b | 132 | |
014a250c | 133 | The file etc/DEBUG describes how to debug Emacs bugs. |
d1208b8b | 134 | |
27e8e710 | 135 | Avoid using `defadvice' or `eval-after-load' for Lisp |
d1208b8b | 136 | code to be included in Emacs. |