CONTRIBUTE 8.11 KB
Newer Older
1
Copyright (C) 2006-2014 Free Software Foundation, Inc.
Juri Linkov's avatar
Juri Linkov committed
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
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
25 26
documentation, find and report bugs, check if existing bug reports
are fixed in newer versions of Emacs, contribute to the Emacs web
Juri Linkov's avatar
Juri Linkov committed
27 28 29 30 31 32 33
pages, or develop a package that works with Emacs.

Here are some style and legal conventions for contributors to Emacs:


* Coding Standards

34
Contributed code should follow the GNU Coding Standards.
Juri Linkov's avatar
Juri Linkov committed
35 36 37 38 39 40

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.

Glenn Morris's avatar
Glenn Morris committed
41
Ref: http://www.gnu.org/prep/standards/
Juri Linkov's avatar
Juri Linkov committed
42 43 44 45 46 47
Ref: GNU Coding Standards Info Manual
Ref: The "Tips" Appendix in the Emacs Lisp Reference.


* Copyright Assignment

48 49 50 51 52 53 54 55
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 .
Juri Linkov's avatar
Juri Linkov committed
56

57 58 59 60
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.
Glenn Morris's avatar
Glenn Morris committed
61 62 63 64

(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.)
65 66

A copyright disclaimer is also a possibility, but we prefer an assignment.
67 68 69 70 71
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.

72 73 74
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.
Juri Linkov's avatar
Juri Linkov committed
75 76 77

* Getting the Source Code

78
The latest version of the Emacs source code can be downloaded from the
79 80 81 82
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.
Juri Linkov's avatar
Juri Linkov committed
83

84 85
After you have downloaded the repository source, you should read the file
INSTALL.REPO for build instructions (they differ to some extent from a
Juri Linkov's avatar
Juri Linkov committed
86 87 88 89 90 91 92 93 94 95 96
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
97 98 99 100 101 102
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.
Juri Linkov's avatar
Juri Linkov committed
103 104 105

** Description

Glenn Morris's avatar
Glenn Morris committed
106
For bug fixes, a description of the bug and how your patch fixes it.
Juri Linkov's avatar
Juri Linkov committed
107

Glenn Morris's avatar
Glenn Morris committed
108
For new features, a description of the feature and your implementation.
Juri Linkov's avatar
Juri Linkov committed
109 110 111 112 113

** ChangeLog

A ChangeLog entry as plaintext (separate from the patch).

Glenn Morris's avatar
Glenn Morris committed
114
See the existing ChangeLog files for format and content.  Note that,
Juri Linkov's avatar
Juri Linkov committed
115 116 117 118 119 120
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.

121 122 123 124 125 126
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.)

Juri Linkov's avatar
Juri Linkov committed
127 128
** The patch itself.

Eric S. Raymond's avatar
Eric S. Raymond committed
129
If you are accessing the Emacs repository, make sure your copy is
130 131 132 133 134
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
Eric S. Raymond's avatar
Eric S. Raymond committed
135
        git diff
136 137
With no repository, you can use
	diff -u OLD NEW
Juri Linkov's avatar
Juri Linkov committed
138 139 140

** Mail format.

Glenn Morris's avatar
Glenn Morris committed
141 142
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.
Juri Linkov's avatar
Juri Linkov committed
143 144 145 146 147 148 149 150

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

151 152 153 154 155
** Do not make formatting changes.

Making cosmetic formatting changes (indentation, etc) makes it harder
to see what you have really changed.

Juri Linkov's avatar
Juri Linkov committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172

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

173
** Write access to the Emacs repository.
Juri Linkov's avatar
Juri Linkov committed
174 175

Once you become a frequent contributor to Emacs, we can consider
176
giving you write access to the version-control repository.
Juri Linkov's avatar
Juri Linkov committed
177 178 179 180 181 182


** Emacs Mailing lists.

Discussion about Emacs development takes place on emacs-devel@gnu.org.

183 184 185
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 .
Juri Linkov's avatar
Juri Linkov committed
186

187 188
You can subscribe to the mailing lists, or see the list archives,
by following links from http://savannah.gnu.org/mail/?group=emacs .
Juri Linkov's avatar
Juri Linkov committed
189 190 191

** Document your changes.

Glenn Morris's avatar
Glenn Morris committed
192
Any change that matters to end-users should have a NEWS entry.
Juri Linkov's avatar
Juri Linkov committed
193

Glenn Morris's avatar
Glenn Morris committed
194 195 196 197
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.
Juri Linkov's avatar
Juri Linkov committed
198 199 200 201 202 203 204 205 206 207 208 209 210

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

211
GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
212
it under the terms of the GNU General Public License as published by
213 214
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
215 216 217 218 219 220 221

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
222
along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Juri Linkov's avatar
Juri Linkov committed
223 224 225 226 227

Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
end: