etc/CONTRIBUTE

   1 Copyright (C) 2006-2015 Free Software Foundation, Inc.
   2 See end for license conditions.
   3
   4
   5                         Contributing to Emacs
   6
   7 Emacs is a collaborative project and we encourage contributions from
   8 anyone and everyone.  If you want to contribute in the way that will
   9 help us most, we recommend (1) fixing reported bugs and (2)
  10 implementing the feature ideas in etc/TODO.  However, if you think of
  11 new features to add, please suggest them too -- we might like your
  12 idea.  Porting to new platforms is also useful, when there is a new
  13 platform, but that is not common nowadays.
  14
  15 For documentation on how to develop Emacs changes, refer to the Emacs
  16 Manual and the Emacs Lisp Reference Manual (both included in the Emacs
  17 distribution).  The web pages in http://www.gnu.org/software/emacs
  18 contain additional information.
  19
  20 You may also want to submit your change so that can be considered for
  21 inclusion in a future version of Emacs (see below).
  22
  23 If you don't feel up to hacking Emacs, there are many other ways to
  24 help.  You can answer questions on the mailing lists, write
  25 documentation, find and report bugs, check if existing bug reports
  26 are fixed in newer versions of Emacs, contribute to the Emacs web
  27 pages, or develop a package that works with Emacs.
  28
  29 Here are some style and legal conventions for contributors to Emacs:
  30
  31
  32 * Coding Standards
  33
  34 Contributed code should follow the GNU Coding Standards.
  35
  36 If it doesn't, we'll need to find someone to fix the code before we
  37 can use it.
  38
  39 Emacs has certain additional style and coding conventions.
  40
  41 Ref: http://www.gnu.org/prep/standards/
  42 Ref: GNU Coding Standards Info Manual
  43 Ref: The "Tips" Appendix in the Emacs Lisp Reference.
  44
  45
  46 * Copyright Assignment
  47
  48 The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
  49 The FSF is a nonprofit with a worldwide mission to promote computer
  50 user freedom and to defend the rights of all free software users.
  51 For general information, see the website http://www.fsf.org/ .
  52
  53 Generally speaking, for non-trivial contributions to GNU Emacs we
  54 require that the copyright be assigned to the FSF.  For the reasons
  55 behind this, see: http://www.gnu.org/licenses/why-assign.html .
  56
  57 Copyright assignment is a simple process.  Residents of some countries
  58 can do it entirely electronically.  We can help you get started, and
  59 answer any questions you may have (or point you to the people with the
  60 answers), at the emacs-devel@gnu.org mailing list.
  61
  62 (Please note: general discussion about why some GNU projects ask
  63 for a copyright assignment is off-topic for emacs-devel.
  64 See gnu-misc-discuss instead.)
  65
  66 A copyright disclaimer is also a possibility, but we prefer an assignment.
  67 Note that the disclaimer, like an assignment, involves you sending
  68 signed paperwork to the FSF (simply saying "this is in the public domain"
  69 is not enough).  Also, a disclaimer cannot be applied to future work, it
  70 has to be repeated each time you want to send something new.
  71
  72 We can accept small changes (roughly, fewer than 15 lines) without
  73 an assignment.  This is a cumulative limit (e.g. three separate 5 line
  74 patches) over all your contributions.
  75
  76 * Getting the Source Code
  77
  78 The latest version of the Emacs source code can be downloaded from the
  79 Savannah web site.  It is important to write your patch based on the
  80 latest version.  If you start from an older version, your patch may be
  81 outdated (so that maintainers will have a hard time applying it), or
  82 changes in Emacs may have made your patch unnecessary.
  83
  84 After you have downloaded the repository source, you should read the file
  85 INSTALL.REPO for build instructions (they differ to some extent from a
  86 normal build).
  87
  88 Ref: http://savannah.gnu.org/projects/emacs
  89
  90
  91 * Submitting Patches
  92
  93 Every patch must have several pieces of information before we
  94 can properly evaluate it.
  95
  96 When you have all these pieces, bundle them up in a mail message and
  97 send it to the developers.  Sending it to bug-gnu-emacs@gnu.org
  98 (which is the bug/feature list) is recommended, because that list
  99 is coupled to a tracking system that makes it easier to locate patches.
 100 If your patch is not complete and you think it needs more discussion,
 101 you might want to send it to emacs-devel@gnu.org instead.  If you
 102 revise your patch, send it as a followup to the initial topic.
 103
 104 ** Description
 105
 106 For bug fixes, a description of the bug and how your patch fixes it.
 107
 108 For new features, a description of the feature and your implementation.
 109
 110 ** ChangeLog
 111
 112 A ChangeLog entry as plaintext (separate from the patch).
 113
 114 See the existing ChangeLog files for format and content.  Note that,
 115 unlike some other projects, we do require ChangeLogs also for
 116 documentation, i.e. Texinfo files.
 117
 118 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
 119 Manual, for how to write good log entries.
 120
 121 When using git, commit messages should use ChangeLog format, with a
 122 single short line explaining the change, then an empty line, then
 123 unindented ChangeLog entries.  (Essentially, a commit message should
 124 be a duplicate of what the patch adds to the ChangeLog files.  We are
 125 planning to automate this better, to avoid the duplication.)
 126
 127 ** The patch itself.
 128
 129 If you are accessing the Emacs repository, make sure your copy is
 130 up-to-date (e.g. with 'git pull').  You can commit your changes
 131 to a private branch and generate a patch from the master version
 132 by using
 133         git format-patch master
 134 Or you can leave your changes uncommitted and use
 135         git diff
 136 With no repository, you can use
 137         diff -u OLD NEW
 138
 139 ** Mail format.
 140
 141 We prefer to get the patches as plain text, either inline (be careful
 142 your mail client does not change line breaks) or as MIME attachments.
 143
 144 ** Please reread your patch before submitting it.
 145
 146 ** Do not mix changes.
 147
 148 If you send several unrelated changes together, we will ask you to
 149 separate them so we can consider each of the changes by itself.
 150
 151 ** Do not make formatting changes.
 152
 153 Making cosmetic formatting changes (indentation, etc) makes it harder
 154 to see what you have really changed.
 155
 156
 157 * Coding style and conventions.
 158
 159 ** Mandatory reading:
 160
 161 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 162
 163 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 164 included in Emacs.
 165
 166 ** Remove all trailing whitespace in all source and text files.
 167
 168 ** Use ?\s instead of ?  in Lisp code for a space character.
 169
 170
 171 * Supplemental information for Emacs Developers.
 172
 173 ** Write access to the Emacs repository.
 174
 175 Once you become a frequent contributor to Emacs, we can consider
 176 giving you write access to the version-control repository.
 177
 178
 179 ** Emacs Mailing lists.
 180
 181 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 182
 183 Bug reports and fixes, feature requests and implementations should be
 184 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
 185 to the tracker at http://debbugs.gnu.org .
 186
 187 You can subscribe to the mailing lists, or see the list archives,
 188 by following links from http://savannah.gnu.org/mail/?group=emacs .
 189
 190 ** Document your changes.
 191
 192 Any change that matters to end-users should have a NEWS entry.
 193
 194 Think about whether your change requires updating the documentation
 195 (both manuals and doc-strings).  If you know it does not, mark the NEWS
 196 entry with "---".  If you know that *all* the necessary documentation
 197 updates have been made, mark the entry with "+++". Otherwise do not mark it.
 198
 199 ** Understanding Emacs Internals.
 200
 201 The best way to understand Emacs Internals is to read the code,
 202 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 203 of the Emacs Lisp Reference Manual may also help.
 204
 205 The file etc/DEBUG describes how to debug Emacs bugs.
 206
 207
 208 \f
 209 This file is part of GNU Emacs.
 210
 211 GNU Emacs is free software: you can redistribute it and/or modify
 212 it under the terms of the GNU General Public License as published by
 213 the Free Software Foundation, either version 3 of the License, or
 214 (at your option) any later version.
 215
 216 GNU Emacs is distributed in the hope that it will be useful,
 217 but WITHOUT ANY WARRANTY; without even the implied warranty of
 218 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 219 GNU General Public License for more details.
 220
 221 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/>.
 223 \f
 224 Local variables:
 225 mode: outline
 226 paragraph-separate: "[  \f]*$"
 227 end: