Copyright (C) 2006-2015 Free Software Foundation, Inc. See end for license conditions. Contributing to Emacs Emacs is a collaborative project and we encourage contributions from anyone and everyone. If you want to contribute in the way that will help us most, we recommend (1) fixing reported bugs and (2) implementing the feature ideas in etc/TODO. However, if you think of new features to add, please suggest them too -- we might like your idea. Porting to new platforms is also useful, when there is a new platform, but that is not common nowadays. For documentation on how to develop Emacs changes, refer to the Emacs Manual and the Emacs Lisp Reference Manual (both included in the Emacs distribution). The web pages in http://www.gnu.org/software/emacs contain additional information. You may also want to submit your change so that can be considered for inclusion in a future version of Emacs (see below). If you don't feel up to hacking Emacs, there are many other ways to help. You can answer questions on the mailing lists, write documentation, find and report bugs, check if existing bug reports are fixed in newer versions of Emacs, contribute to the Emacs web pages, or develop a package that works with Emacs. Here are some style and legal conventions for contributors to Emacs: * Coding Standards Contributed code should follow the GNU Coding Standards. If it doesn't, we'll need to find someone to fix the code before we can use it. Emacs has certain additional style and coding conventions. Ref: http://www.gnu.org/prep/standards/ Ref: GNU Coding Standards Info Manual Ref: The "Tips" Appendix in the Emacs Lisp Reference. * Copyright Assignment The FSF (Free Software Foundation) is the copyright holder for GNU Emacs. The FSF is a nonprofit with a worldwide mission to promote computer user freedom and to defend the rights of all free software users. For general information, see the website http://www.fsf.org/ . Generally speaking, for non-trivial contributions to GNU Emacs we require that the copyright be assigned to the FSF. For the reasons behind this, see: http://www.gnu.org/licenses/why-assign.html . Copyright assignment is a simple process. Residents of some countries can do it entirely electronically. We can help you get started, and answer any questions you may have (or point you to the people with the answers), at the emacs-devel@gnu.org mailing list. (Please note: general discussion about why some GNU projects ask for a copyright assignment is off-topic for emacs-devel. See gnu-misc-discuss instead.) A copyright disclaimer is also a possibility, but we prefer an assignment. Note that the disclaimer, like an assignment, involves you sending signed paperwork to the FSF (simply saying "this is in the public domain" is not enough). Also, a disclaimer cannot be applied to future work, it has to be repeated each time you want to send something new. We can accept small changes (roughly, fewer than 15 lines) without an assignment. This is a cumulative limit (e.g. three separate 5 line patches) over all your contributions. * Getting the Source Code The latest version of the Emacs source code can be downloaded from the Savannah web site. It is important to write your patch based on the latest version. If you start from an older version, your patch may be outdated (so that maintainers will have a hard time applying it), or changes in Emacs may have made your patch unnecessary. After you have downloaded the repository source, you should read the file INSTALL.REPO for build instructions (they differ to some extent from a normal build). Ref: http://savannah.gnu.org/projects/emacs * Submitting Patches Every patch must have several pieces of information before we can properly evaluate it. When you have all these pieces, bundle them up in a mail message and send it to the developers. Sending it to bug-gnu-emacs@gnu.org (which is the bug/feature list) is recommended, because that list is coupled to a tracking system that makes it easier to locate patches. If your patch is not complete and you think it needs more discussion, you might want to send it to emacs-devel@gnu.org instead. If you revise your patch, send it as a followup to the initial topic. ** Description For bug fixes, a description of the bug and how your patch fixes it. For new features, a description of the feature and your implementation. ** ChangeLog A ChangeLog entry as plaintext (separate from the patch). See the existing ChangeLog files for format and content. Note that, unlike some other projects, we do require ChangeLogs also for documentation, i.e. Texinfo files. Ref: "Change Log Concepts" node of the GNU Coding Standards Info Manual, for how to write good log entries. When using git, commit messages should use ChangeLog format, with a single short line explaining the change, then an empty line, then unindented ChangeLog entries. (Essentially, a commit message should be a duplicate of what the patch adds to the ChangeLog files. We are planning to automate this better, to avoid the duplication.) ** The patch itself. If you are accessing the Emacs repository, make sure your copy is up-to-date (e.g. with 'git pull'). You can commit your changes to a private branch and generate a patch from the master version by using git format-patch master Or you can leave your changes uncommitted and use git diff With no repository, you can use diff -u OLD NEW ** Mail format. We prefer to get the patches as plain text, either inline (be careful your mail client does not change line breaks) or as MIME attachments. ** Please reread your patch before submitting it. ** Do not mix changes. If you send several unrelated changes together, we will ask you to separate them so we can consider each of the changes by itself. ** Do not make formatting changes. Making cosmetic formatting changes (indentation, etc) makes it harder to see what you have really changed. * Coding style and conventions. ** Mandatory reading: The "Tips and Conventions" Appendix of the Emacs Lisp Reference. ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be included in Emacs. ** Remove all trailing whitespace in all source and text files. ** Use ?\s instead of ? in Lisp code for a space character. * Supplemental information for Emacs Developers. ** Write access to the Emacs repository. Once you become a frequent contributor to Emacs, we can consider giving you write access to the version-control repository. ** Emacs Mailing lists. Discussion about Emacs development takes place on emacs-devel@gnu.org. Bug reports and fixes, feature requests and implementations should be sent to bug-gnu-emacs@gnu.org, the bug/feature list. This is coupled to the tracker at http://debbugs.gnu.org . You can subscribe to the mailing lists, or see the list archives, by following links from http://savannah.gnu.org/mail/?group=emacs . ** Document your changes. Any change that matters to end-users should have a NEWS entry. Think about whether your change requires updating the documentation (both manuals and doc-strings). If you know it does not, mark the NEWS entry with "---". If you know that *all* the necessary documentation updates have been made, mark the entry with "+++". Otherwise do not mark it. ** Understanding Emacs Internals. The best way to understand Emacs Internals is to read the code, but the nodes "Tips" and "GNU Emacs Internals" in the Appendix of the Emacs Lisp Reference Manual may also help. The file etc/DEBUG describes how to debug Emacs bugs. This file is part of GNU Emacs. GNU Emacs is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. GNU Emacs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Emacs. If not, see . Local variables: mode: outline paragraph-separate: "[ ]*$" end: