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