etc/CONTRIBUTE

   1 Copyright (C) 2006, 2007, 2008  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 Standard.
  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_toc.html
  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 without legal papers, and for medium-size
  48 changes a copyright disclaimer is ok too.  To accept substantial
  49 contributions from you, we need a copyright assignment form filled out
  50 and filed with the FSF.
  51
  52 Contact us 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 CVS or Arch from
  58 the Savannah web site.  It is important to write your patch based on
  59 this version; if you start from an older version, your patch may be
  60 outdated when you write it, and maintainers will have a hard time
  61 applying it.
  62
  63 After you have downloaded the CVS source, you should read the file
  64 INSTALL.CVS 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 emacs-pretest-bug@gnu.org or emacs-devel@gnu.org.
  77
  78 All subsequent discussion should also be sent to the 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 CVS repository use
 103         cvs update; cvs diff -cp
 104 else, use
 105         diff -cp OLD NEW
 106
 107 If your version of diff does not support these options, then get the
 108 latest version of GNU Diff.
 109
 110 ** Mail format.
 111
 112 We prefer to get the patches as inline plain text.
 113
 114 Please be aware of line wrapping which will make the patch unreadable
 115 and useless for us.  To avoid that, you can use MIME attachments or,
 116 as a last resort, uuencoded gzipped text.
 117
 118 ** Please reread your patch before submitting it.
 119
 120 ** Do not mix changes.
 121
 122 If you send several unrelated changes together, we will ask you to
 123 separate them so we can consider each of the changes by itself.
 124
 125
 126 * Coding style and conventions.
 127
 128 ** Mandatory reading:
 129
 130 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 131
 132 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 133 included in Emacs.
 134
 135 ** Remove all trailing whitespace in all source and text files.
 136
 137 ** Use ?\s instead of ?  in Lisp code for a space character.
 138
 139
 140 * Supplemental information for Emacs Developers.
 141
 142 ** Write access to Emacs' CVS repository.
 143
 144 Once you become a frequent contributor to Emacs, we can consider
 145 giving you write access to the CVS repository.
 146
 147
 148 ** Emacs Mailing lists.
 149
 150 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 151
 152 Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
 153
 154 Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
 155
 156 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
 157
 158 You can find the mailing lists archives at lists.gnu.org or gmane.org.
 159
 160
 161 ** Document your changes.
 162
 163 Think carefully about whether your change requires updating the
 164 documentation.  If it does, you can either do this yourself or add an
 165 item to the NEWS file.
 166
 167 If you document your change in NEWS, please mark the NEWS entry with
 168 the documentation status of the change: if you submit the changes for
 169 the manuals, mark it with "+++"; if it doesn't need to be documented,
 170 mark it with "---"; if it needs to be documented, but you didn't
 171 submit documentation changes, leave the NEWS entry unmarked.  (These
 172 marks are checked by the Emacs maintainers to make sure every change
 173 was reflected in the manuals.)
 174
 175
 176 ** Understanding Emacs Internals.
 177
 178 The best way to understand Emacs Internals is to read the code,
 179 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 180 of the Emacs Lisp Reference Manual may also help.
 181
 182 The file etc/DEBUG describes how to debug Emacs bugs.
 183
 184
 185 \f
 186 This file is part of GNU Emacs.
 187
 188 GNU Emacs is free software; you can redistribute it and/or modify
 189 it under the terms of the GNU General Public License as published by
 190 the Free Software Foundation; either version 3, or (at your option)
 191 any later version.
 192
 193 GNU Emacs is distributed in the hope that it will be useful,
 194 but WITHOUT ANY WARRANTY; without even the implied warranty of
 195 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 196 GNU General Public License for more details.
 197
 198 You should have received a copy of the GNU General Public License
 199 along with GNU Emacs; see the file COPYING.  If not, write to the
 200 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 201 Boston, MA 02110-1301, USA.
 202 \f
 203 Local variables:
 204 mode: outline
 205 paragraph-separate: "[  \f]*$"
 206 end:
 207