CONTRIBUTE 12.3 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
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.

15
For documentation on Emacs (to understand how to implement your desired change), refer to:
Juri Linkov's avatar
Juri Linkov committed
16

17 18 19
- the Emacs Manual
  http://www.gnu.org/software/emacs/manual/emacs.html
  (info "(Emacs)Top")
Juri Linkov's avatar
Juri Linkov committed
20

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
- the Emacs Lisp Reference Manual
  http://www.gnu.org/software/emacs/manual/elisp.html
  (info "(elisp)Top")

- http://www.gnu.org/software/emacs

- http://www.emacswiki.org/

There are many ways to contribute to Emacs:

- implement a new feature, and submit a patch (see "Submitting
  Patches" below).

- answer questions on the Emacs user mailing list
  https://lists.gnu.org/mailman/listinfo/help-gnu-emacs

- write documentation, either on the wiki, or in the Emacs source
  repository (see "Submitting Patches" below)

- find and report bugs; use M-x report-emacs-bug

- check if existing bug reports are fixed in newer versions of Emacs
  http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs

- develop a package that works with Emacs, and publish it on your own or in Gnu ELPA.
Juri Linkov's avatar
Juri Linkov committed
46 47 48 49 50 51

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


* Coding Standards

52 53 54
Contributed code should follow the GNU Coding Standards
(http://www.gnu.org/prep/standards/ - may also be available in info on
your system).
Juri Linkov's avatar
Juri Linkov committed
55 56 57 58

If it doesn't, we'll need to find someone to fix the code before we
can use it.

59 60 61 62 63
Emacs has additional style and coding conventions:

- the "Tips" Appendix in the Emacs Lisp Reference
  http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
  (info "(elisp)Tips").
Juri Linkov's avatar
Juri Linkov committed
64

65 66
- Avoid using `defadvice' or `eval-after-load' for Lisp code to be
  included in Emacs.
Juri Linkov's avatar
Juri Linkov committed
67

68 69 70 71 72 73
- Remove all trailing whitespace in all source and text files.

- Emacs has no convention on whether to use tabs in source code, but
  please don't change whitespace in the files you edit.

- Use ?\s instead of ?  in Lisp code for a space character.
Juri Linkov's avatar
Juri Linkov committed
74 75 76

* Copyright Assignment

77 78 79 80 81 82 83 84
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
85

86 87 88 89
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.
90 91 92 93

(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.)
94 95

A copyright disclaimer is also a possibility, but we prefer an assignment.
96 97 98 99 100
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.

101 102 103
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
104 105 106

* Getting the Source Code

107 108 109 110 111 112 113
The current working version of the Emacs source code is stored in a
git repository on the Savannah web site
(http://savannah.gnu.org/projects/emacs).  It is important to write
your patch based on the current working 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
114

115 116
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
117 118 119 120 121 122 123 124
normal build).

* 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
125 126 127 128 129 130
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
131 132 133

** Description

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

Glenn Morris's avatar
Glenn Morris committed
136
For new features, a description of the feature and your implementation.
Juri Linkov's avatar
Juri Linkov committed
137 138 139 140 141

** ChangeLog

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

Glenn Morris's avatar
Glenn Morris committed
142
See the existing ChangeLog files for format and content.  Note that,
143
unlike some other projects, we do require ChangeLogs for
Juri Linkov's avatar
Juri Linkov committed
144 145 146 147
documentation, i.e. Texinfo files.

Ref: "Change Log Concepts" node of the GNU Coding Standards Info
Manual, for how to write good log entries.
148
http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
Juri Linkov's avatar
Juri Linkov committed
149

150 151 152 153 154 155
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
156 157
** The patch itself.

Eric S. Raymond's avatar
Eric S. Raymond committed
158
If you are accessing the Emacs repository, make sure your copy is
159 160 161 162 163
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
164
        git diff
165 166
With no repository, you can use
	diff -u OLD NEW
Juri Linkov's avatar
Juri Linkov committed
167 168 169

** Mail format.

Glenn Morris's avatar
Glenn Morris committed
170 171
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
172 173 174 175 176 177 178 179

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

180 181 182 183 184
** 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
185

186
* Supplemental information for Emacs Developers.
Juri Linkov's avatar
Juri Linkov committed
187

188 189
An "Emacs Developer" is someone who contributes a lot of code or
documentation to the Emacs repository.
Juri Linkov's avatar
Juri Linkov committed
190

191
** Write access to the Emacs repository.
Juri Linkov's avatar
Juri Linkov committed
192

193 194 195
Once you become a frequent contributor to Emacs, we can consider
giving you write access to the version-control repository. Request
access on the emacs-devel@gnu.org mailing list.
Juri Linkov's avatar
Juri Linkov committed
196

197
** Using the Emacs repository
Juri Linkov's avatar
Juri Linkov committed
198

199
Emacs uses git for the source code repository.
Juri Linkov's avatar
Juri Linkov committed
200

201 202 203
See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
advanced information.
Juri Linkov's avatar
Juri Linkov committed
204

205
Alternately, see admin/notes/git-workflow.
Juri Linkov's avatar
Juri Linkov committed
206

207 208 209 210
If committing changes written by someone else, make the ChangeLog
entry in their name, not yours. git distinguishes between the author
and the committer; use the --author option on the commit command to
specify the actual author; the committer defaults to you.
Juri Linkov's avatar
Juri Linkov committed
211

212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282
** Changelog notes

- Preferred form for several entries with the same content:

   * help.el (view-lossage):
   * kmacro.el (kmacro-edit-lossage):
   * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.

  (Rather than anything involving "ditto" and suchlike.)

- Emacs generally follows the GNU coding standards when it comes to
  ChangeLogs:
  http://www.gnu.org/prep/standards/html_node/Change-Logs.html .  One
  exception is that we still sometimes quote `like-this' (as the
  standards used to recommend) rather than 'like-this' (as they do
  now), because `...' is so widely used elsewhere in Emacs.

- There are multiple ChangeLogs in the emacs source; roughly one per
  high-level directory. The ChangeLog entry for a commit belongs in the
  lowest ChangeLog that is higher than or at the same level as any file
  changed by the commit.

- In ChangeLog files, there is no standard or recommended way to
  identify revisions.

  One way to identify revisions is by quoting their summary line.
  Another is with an action stamp - an RFC3339 date followed by !
  followed by the committer's email - for example,
  "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
  will suffice.

- There is no need to make separate change log entries for files such
  as NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration
  of files such as 'configure'.  "There is no need" means you don't
  have to, but you can if you want to.

** branches

Development normally takes places on the trunk.
Sometimes specialized features are developed on separate branches
before possibly being merged to the trunk.

Development is discussed on the emacs-devel mailing list.

Sometime before the release of a new major version of Emacs a "feature
freeze" is imposed on the trunk, to prepare for creating a release
branch.  No new features may be added to the trunk after this point,
until the release branch is created. This freeze is announced on the
emacs-devel mailing list, and not anywhere else.

For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for
23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x.

You must follow emacs-devel to know exactly what kinds of changes are
allowed on what branch at any time. Announcements about the freeze
(and other important events) will contain "ANNOUNCE" in the subject.

If you are fixing a bug that exists in the current release, be sure to
commit it to the release branch; it will be merged to the master
branch later.

The exception is, if you know that the change will be difficult to
merge to the trunk (eg because the trunk code has changed a lot).  In
that case, it's helpful if you can apply the change to both trunk and
branch yourself.  Indicate in the release branch commit log that there
is no need to merge the commit to the trunk; start the commit message
with "Backport:".  This is helpful for the person merging the release
branch to the trunk (it is handled automatically by gitmerge.el).


** Other process information
Juri Linkov's avatar
Juri Linkov committed
283

284 285
See all the files in admin/notes/* . In particular, see
admin/notes/newfile, see admin/notes/repo.
Juri Linkov's avatar
Juri Linkov committed
286 287 288 289 290

** Emacs Mailing lists.

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

291 292 293
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
294

295 296
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
297 298 299

** Document your changes.

300
Any change that matters to end-users should have an entry in etc/NEWS.
Juri Linkov's avatar
Juri Linkov committed
301

Glenn Morris's avatar
Glenn Morris committed
302 303 304 305
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
306 307 308 309 310 311 312 313 314 315 316 317 318

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

319
GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
320
it under the terms of the GNU General Public License as published by
321 322
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
323 324 325 326 327 328 329

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
330
along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Juri Linkov's avatar
Juri Linkov committed
331 332 333 334 335

Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
end: