code.delx.au - gnu-emacs/blob - etc/CONTRIBUTE

   1 Copyright (C) 2006-2013 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.  If you live in the US, you
  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 A copyright disclaimer is also a possibility, but we prefer an assignment.
  63 Note that the disclaimer, like an assignment, involves you sending
  64 signed paperwork to the FSF (simply saying "this is in the public domain"
  65 is not enough).  Also, a disclaimer cannot be applied to future work, it
  66 has to be repeated each time you want to send something new.
  67
  68 We can accept small changes (roughly, fewer than 15 lines) without
  69 an assignment.  This is a cumulative limit (e.g. three separate 5 line
  70 patches) over all your contributions.
  71
  72 * Getting the Source Code
  73
  74 The latest version of Emacs can be downloaded using Bazaar from the
  75 Savannah web site.  It is important to write your patch based on the
  76 latest version.  If you start from an older version, your patch may be
  77 outdated (so that maintainers will have a hard time applying it), or
  78 changes in Emacs may have made your patch unnecessary.
  79
  80 After you have downloaded the Bazaar source, you should read the file
  81 INSTALL.BZR for build instructions (they differ to some extent from a
  82 normal build).
  83
  84 Ref: http://savannah.gnu.org/projects/emacs
  85
  86
  87 * Submitting Patches
  88
  89 Every patch must have several pieces of information before we
  90 can properly evaluate it.
  91
  92 When you have all these pieces, bundle them up in a mail message and
  93 send it to the developers.  Sending it to bug-gnu-emacs@gnu.org
  94 (which is the bug/feature list) is recommended, because that list
  95 is coupled to a tracking system that makes it easier to locate patches.
  96 If your patch is not complete and you think it needs more discussion,
  97 you might want to send it to emacs-devel@gnu.org instead.  If you
  98 revise your patch, send it as a followup to the initial topic.
  99
 100 ** Description
 101
 102 For bug fixes, a description of the bug and how your patch fixes this
 103 bug.
 104
 105 For new features, a description of the feature and your implementation.
 106
 107 ** ChangeLog
 108
 109 A ChangeLog entry as plaintext (separate from the patch).
 110
 111 See the various ChangeLog files for format and content.  Note that,
 112 unlike some other projects, we do require ChangeLogs also for
 113 documentation, i.e. Texinfo files.
 114
 115 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
 116 Manual, for how to write good log entries.
 117
 118 ** The patch itself.
 119
 120 Please use "Context Diff" format.
 121
 122 If you are accessing the Bazaar repository, make sure your copy is
 123 up-to-date (e.g. with `bzr pull'), then use
 124         bzr diff --no-aliases --diff-options=-cp
 125 Else, use
 126         diff -cp OLD NEW
 127
 128 If your version of diff does not support these options, then get the
 129 latest version of GNU Diff.
 130
 131 ** Mail format.
 132
 133 We prefer to get the patches as inline plain text.
 134
 135 Please be aware of line wrapping which will make the patch unreadable
 136 and useless for us.  To avoid that, you can use MIME attachments or,
 137 as a last resort, uuencoded gzipped text.
 138
 139 ** Please reread your patch before submitting it.
 140
 141 ** Do not mix changes.
 142
 143 If you send several unrelated changes together, we will ask you to
 144 separate them so we can consider each of the changes by itself.
 145
 146 ** Do not make formatting changes.
 147
 148 Making cosmetic formatting changes (indentation, etc) makes it harder
 149 to see what you have really changed.
 150
 151
 152 * Coding style and conventions.
 153
 154 ** Mandatory reading:
 155
 156 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 157
 158 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 159 included in Emacs.
 160
 161 ** Remove all trailing whitespace in all source and text files.
 162
 163 ** Use ?\s instead of ?  in Lisp code for a space character.
 164
 165
 166 * Supplemental information for Emacs Developers.
 167
 168 ** Write access to the Emacs repository.
 169
 170 Once you become a frequent contributor to Emacs, we can consider
 171 giving you write access to the Bazaar repository.
 172
 173
 174 ** Emacs Mailing lists.
 175
 176 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 177
 178 Bug reports and fixes, feature requests and implementations should be
 179 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
 180 to the tracker at http://debbugs.gnu.org .
 181
 182 You can subscribe to the mailing lists, or see the list archives,
 183 by following links from http://savannah.gnu.org/mail/?group=emacs .
 184
 185 ** Document your changes.
 186
 187 Think carefully about whether your change requires updating the
 188 documentation.  If it does, you can either do this yourself or add an
 189 item to the NEWS file.
 190
 191 If you document your change in NEWS, please mark the NEWS entry with
 192 the documentation status of the change: if you submit the changes for
 193 the manuals, mark it with "+++"; if it doesn't need to be documented,
 194 mark it with "---"; if it needs to be documented, but you didn't
 195 submit documentation changes, leave the NEWS entry unmarked.  (These
 196 marks are checked by the Emacs maintainers to make sure every change
 197 was reflected in the manuals.)
 198
 199
 200 ** Understanding Emacs Internals.
 201
 202 The best way to understand Emacs Internals is to read the code,
 203 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 204 of the Emacs Lisp Reference Manual may also help.
 205
 206 The file etc/DEBUG describes how to debug Emacs bugs.
 207
 208
 209 \f
 210 This file is part of GNU Emacs.
 211
 212 GNU Emacs is free software: you can redistribute it and/or modify
 213 it under the terms of the GNU General Public License as published by
 214 the Free Software Foundation, either version 3 of the License, or
 215 (at your option) any later version.
 216
 217 GNU Emacs is distributed in the hope that it will be useful,
 218 but WITHOUT ANY WARRANTY; without even the implied warranty of
 219 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 220 GNU General Public License for more details.
 221
 222 You should have received a copy of the GNU General Public License
 223 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 224 \f
 225 Local variables:
 226 mode: outline
 227 paragraph-separate: "[  \f]*$"
 228 end:
 229