etc/CONTRIBUTE

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