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.

** 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.

** 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, which should be separate from the rest of the patch.

Normally the git commit message should contain the ChangeLog entry,
starting with a single short line explaining the change, then an empty
line, then ChangeLog entries.  Append a "Fixes:" line if the commit
fixes a bug numbered at http://debbugs.gnu.org.  Here is an indented
example (the actual commit message should not be indented):

	Deactivate shifted region

	Do not silently extend a region that is not highlighted;
	this can happen after a shift.
	* doc/emacs/mark.texi (Shift Selection): Document the change.
	* lisp/window.el (handle-select-window):
	* src/frame.c (Fhandle_switch_frame, Fselected_frame):
	Deactivate the mark.
	Fixes: bug#19003

If you don't use git, the ChangeLog entry should be in plaintext and
should be separate from the patch.

Ref: "Change Log Concepts" node of the GNU Coding Standards Info
Manual, for how to write good log entries.  Unlike some other
projects, we require ChangeLog entries also for documentation, i.e.,
Texinfo files.

If you use Emacs VC, one way to format ChangeLog entries is to create
a top-level ChangeLog file, and update it with 'C-x 4 a' file as
usual.  Do not register the ChangeLog file under git; instead, use
'C-c C-a' to insert its contents into into your *vc-log* buffer.
Alternatively, you can use vc-dwim as described in ../admin/repo.

** 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
With no repository, you can use
	diff -u OLD NEW

** Please reread your patch before submitting it.

** 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.
To send a git-format patch inline, you can use
	git send-email 0001-FOO.patch


* 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.


\f
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 <http://www.gnu.org/licenses/>.
\f
Local variables:
mode: outline
paragraph-separate: "[ 	\f]*$"
end: