etc/CONTRIBUTE

   1 Copyright (C) 2006, 2007  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 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
  86 implementation.
  87
  88 ** ChangeLog
  89
  90 A ChangeLog entry as plaintext (separate from the patch).
  91
  92 See the various ChangeLog files for format and content. Note that,
  93 unlike some other projects, we do require ChangeLogs also for
  94 documentation, i.e. Texinfo files.
  95
  96 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
  97 Manual, for how to write good log entries.
  98
  99 ** The patch itself.
 100
 101 Please use "Context Diff" format.
 102
 103 If you are accessing the CVS repository use
 104         cvs update; cvs diff -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
 127 * Coding style and conventions.
 128
 129 ** Mandatory reading:
 130
 131 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 132
 133 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 134 included in Emacs.
 135
 136 ** Remove all trailing whitespace in all source and text files.
 137
 138 ** Use ?\s instead of ?  in Lisp code for a space character.
 139
 140
 141 * Supplemental information for Emacs Developers.
 142
 143 ** Write access to Emacs' CVS repository.
 144
 145 Once you become a frequent contributor to Emacs, we can consider
 146 giving you write access to the CVS repository.
 147
 148
 149 ** Emacs Mailing lists.
 150
 151 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 152
 153 Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
 154
 155 Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
 156
 157 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
 158
 159 You can find the mailing lists archives at lists.gnu.org or gmane.org.
 160
 161
 162 ** Document your changes.
 163
 164 Think carefully about whether your change requires updating the
 165 documentation.  If it does, you can either do this yourself or add an
 166 item to the NEWS file.
 167
 168 If you document your change in NEWS, please mark the NEWS entry with
 169 the documentation status of the change: if you submit the changes for
 170 the manuals, mark it with "+++"; if it doesn't need to be documented,
 171 mark it with "---"; if it needs to be documented, but you didn't
 172 submit documentation changes, leave the NEWS entry unmarked.  (These
 173 marks are checked by the Emacs maintainers to make sure every change
 174 was reflected in the manuals.)
 175
 176
 177 ** Understanding Emacs Internals.
 178
 179 The best way to understand Emacs Internals is to read the code,
 180 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 181 of the Emacs Lisp Reference Manual may also help.
 182
 183 The file etc/DEBUG describes how to debug Emacs bugs.
 184
 185
 186
 187 * How to Maintain Copyright Years for GNU Emacs
 188
 189 See admin/notes/copyright.
 190
 191 ** Our lawyer says it is ok if we add, to each file that has been in Emacs
 192 since Emacs 21 came out in 2001, all the subsequent years.  We don't
 193 need to check whether *that file* was changed in those years.
 194 It's sufficient that *Emacs* was changed in those years (and it was!).
 195
 196 ** For those files that have been added since then, we should add
 197 the year it was added to Emacs, and all subsequent years.
 198
 199 ** For the refcards under etc/, it's ok to simply use the latest year
 200 (typically in a `\def\year{YEAR}' expression) for the rendered copyright
 201 notice, while maintaining the full list of years in the copyright notice
 202 in the comments.
 203
 204
 205 \f
 206 This file is part of GNU Emacs.
 207
 208 GNU Emacs is free software; you can redistribute it and/or modify
 209 it under the terms of the GNU General Public License as published by
 210 the Free Software Foundation; either version 3, or (at your option)
 211 any later version.
 212
 213 GNU Emacs is distributed in the hope that it will be useful,
 214 but WITHOUT ANY WARRANTY; without even the implied warranty of
 215 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 216 GNU General Public License for more details.
 217
 218 You should have received a copy of the GNU General Public License
 219 along with GNU Emacs; see the file COPYING.  If not, write to the
 220 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 221 Boston, MA 02110-1301, USA.
 222 \f
 223 Local variables:
 224 mode: outline
 225 paragraph-separate: "[  \f]*$"
 226 end:
 227