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 bug-gnu-emacs@gnu.org or emacs-devel@gnu.org.
  77
  78 All subsequent discussion should be sent to the same mailing list.
  79
  80 ** Description
  81
  82 For bug fixes, a description of the bug and how your patch fixes this
  83 bug.
  84
  85 For new features, a description of the feature and your implementation.
  86
  87 ** ChangeLog
  88
  89 A ChangeLog entry as plaintext (separate from the patch).
  90
  91 See the various ChangeLog files for format and content.  Note that,
  92 unlike some other projects, we do require ChangeLogs also for
  93 documentation, i.e. Texinfo files.
  94
  95 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
  96 Manual, for how to write good log entries.
  97
  98 ** The patch itself.
  99
 100 Please use "Context Diff" format.
 101
 102 If you are accessing the Bazaar repository, make sure your copy is
 103 up-to-date (e.g. with `bzr pull'), then use
 104         bzr diff --no-aliases --diff-options=-cp
 105 Else, use
 106         diff -cp OLD NEW
 107
 108 If your version of diff does not support these options, then get the
 109 latest version of GNU Diff.
 110
 111 ** Mail format.
 112
 113 We prefer to get the patches as inline plain text.
 114
 115 Please be aware of line wrapping which will make the patch unreadable
 116 and useless for us.  To avoid that, you can use MIME attachments or,
 117 as a last resort, uuencoded gzipped text.
 118
 119 ** Please reread your patch before submitting it.
 120
 121 ** Do not mix changes.
 122
 123 If you send several unrelated changes together, we will ask you to
 124 separate them so we can consider each of the changes by itself.
 125
 126 ** Do not make formatting changes.
 127
 128 Making cosmetic formatting changes (indentation, etc) makes it harder
 129 to see what you have really changed.
 130
 131
 132 * Coding style and conventions.
 133
 134 ** Mandatory reading:
 135
 136 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 137
 138 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 139 included in Emacs.
 140
 141 ** Remove all trailing whitespace in all source and text files.
 142
 143 ** Use ?\s instead of ?  in Lisp code for a space character.
 144
 145
 146 * Supplemental information for Emacs Developers.
 147
 148 ** Write access to the Emacs repository.
 149
 150 Once you become a frequent contributor to Emacs, we can consider
 151 giving you write access to the Bazaar repository.
 152
 153
 154 ** Emacs Mailing lists.
 155
 156 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 157
 158 Bug reports and feature requests are sent to bug-gnu-emacs@gnu.org.
 159
 160 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
 161
 162 You can find the mailing lists archives at lists.gnu.org or gmane.org.
 163
 164
 165 ** Document your changes.
 166
 167 Think carefully about whether your change requires updating the
 168 documentation.  If it does, you can either do this yourself or add an
 169 item to the NEWS file.
 170
 171 If you document your change in NEWS, please mark the NEWS entry with
 172 the documentation status of the change: if you submit the changes for
 173 the manuals, mark it with "+++"; if it doesn't need to be documented,
 174 mark it with "---"; if it needs to be documented, but you didn't
 175 submit documentation changes, leave the NEWS entry unmarked.  (These
 176 marks are checked by the Emacs maintainers to make sure every change
 177 was reflected in the manuals.)
 178
 179
 180 ** Understanding Emacs Internals.
 181
 182 The best way to understand Emacs Internals is to read the code,
 183 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 184 of the Emacs Lisp Reference Manual may also help.
 185
 186 The file etc/DEBUG describes how to debug Emacs bugs.
 187
 188
 189 \f
 190 This file is part of GNU Emacs.
 191
 192 GNU Emacs is free software: you can redistribute it and/or modify
 193 it under the terms of the GNU General Public License as published by
 194 the Free Software Foundation, either version 3 of the License, or
 195 (at your option) any later version.
 196
 197 GNU Emacs is distributed in the hope that it will be useful,
 198 but WITHOUT ANY WARRANTY; without even the implied warranty of
 199 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 200 GNU General Public License for more details.
 201
 202 You should have received a copy of the GNU General Public License
 203 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 204 \f
 205 Local variables:
 206 mode: outline
 207 paragraph-separate: "[  \f]*$"
 208 end:
 209