CONTRIBUTE

   1 Copyright (C) 2006, 2007  Free Software Foundation, Inc.
   2 Copying and distribution of this file, with or without modification,
   3 are permitted provided the copyright notice and this notice are preserved.
   4
   5
   6                         Contributing to Emacs
   7
   8 Emacs is a collaborative project and we encourage contributions from
   9 anyone and everyone.  If you want to contribute in the way that will
  10 help us most, we recommend (1) fixing reported bugs and (2)
  11 implementing the feature ideas in etc/TODO.  However, if you think of
  12 new features to add, please suggest them too -- we might like your
  13 idea.  Porting to new platforms is also useful, when there is a new
  14 platform, but that is not common nowadays.
  15
  16 For documentation on how to develop Emacs changes, refer to the Emacs
  17 Manual and the Emacs Lisp Reference Manual (both included in the Emacs
  18 distribution).  The web pages in http://www.gnu.org/software/emacs
  19 contain additional information.
  20
  21 You may also want to submit your change so that can be considered for
  22 inclusion in a future version of Emacs (see below).
  23
  24 If you don't feel up to hacking Emacs, there are many other ways to
  25 help.  You can answer questions on the mailing lists, write
  26 documentation, find and report bugs, 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 Standard.
  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_toc.html
  42 Ref: GNU Coding Standards Info Manual
  43 Ref: The "Tips" Appendix in the Emacs Lisp Reference.
  44
  45
  46 * Copyright Assignment
  47
  48 We can accept small changes without legal papers, and for medium-size
  49 changes a copyright disclaimer is ok too.  To accept substantial
  50 contributions from you, we need a copyright assignment form filled out
  51 and filed with the FSF.
  52
  53 Contact us at emacs-devel@gnu.org to obtain the relevant forms.
  54
  55
  56 * Getting the Source Code
  57
  58 The latest version of Emacs can be downloaded using CVS or Arch from
  59 the Savannah web site.  It is important to write your patch based on
  60 this version; if you start from an older version, your patch may be
  61 outdated when you write it, and maintainers will have hard time
  62 applying it.
  63
  64 After you have downloaded the CVS source, you should read the file
  65 INSTALL.CVS for build instructions (they differ to some extent from a
  66 normal build).
  67
  68 Ref: http://savannah.gnu.org/projects/emacs
  69
  70
  71 * Submitting Patches
  72
  73 Every patch must have several pieces of information before we
  74 can properly evaluate it.
  75
  76 When you have all these pieces, bundle them up in a mail message and
  77 send it to emacs-pretest-bug@gnu.org or emacs-devel@gnu.org.
  78
  79 All subsequent discussion should also be sent to the mailing list.
  80
  81 ** Description
  82
  83 For bug fixes, a description of the bug and how your patch fixes this
  84 bug.
  85
  86 For new features, a description of the feature and your
  87 implementation.
  88
  89 ** ChangeLog
  90
  91 A ChangeLog entry as plaintext (separate from the patch).
  92
  93 See the various ChangeLog files for format and content. Note that,
  94 unlike some other projects, we do require ChangeLogs also for
  95 documentation, i.e. Texinfo files.
  96
  97 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
  98 Manual, for how to write good log entries.
  99
 100 ** The patch itself.
 101
 102 Please use "Context Diff" format.
 103
 104 If you are accessing the CVS repository use
 105         cvs update; cvs diff -cp
 106 else, use
 107         diff -cp OLD NEW
 108
 109 If your version of diff does not support these options, then get the
 110 latest version of GNU Diff.
 111
 112 ** Mail format.
 113
 114 We prefer to get the patches as inline plain text.
 115
 116 Please be aware of line wrapping which will make the patch unreadable
 117 and useless for us.  To avoid that, you can use MIME attachments or,
 118 as a last resort, uuencoded gzipped text.
 119
 120 ** Please reread your patch before submitting it.
 121
 122 ** Do not mix changes.
 123
 124 If you send several unrelated changes together, we will ask you to
 125 separate them so we can consider each of the changes by itself.
 126
 127
 128 * Coding style and conventions.
 129
 130 ** Mandatory reading:
 131
 132 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 133
 134 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 135 included in Emacs.
 136
 137 ** Remove all trailing whitespace in all source and text files.
 138
 139 ** Use ?\s instead of ?  in Lisp code for a space character.
 140
 141
 142 * Supplemental information for Emacs Developers.
 143
 144 ** Write access to Emacs' CVS repository.
 145
 146 Once you become a frequent contributor to Emacs, we can consider
 147 giving you write access to the CVS repository.
 148
 149
 150 ** Emacs Mailing lists.
 151
 152 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 153
 154 Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
 155
 156 Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
 157
 158 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
 159
 160 You can find the mailing lists archives at lists.gnu.org or gmane.org.
 161
 162
 163 ** Document your changes.
 164
 165 Think carefully about whether your change requires updating the
 166 documentation.  If it does, you can either do this yourself or add an
 167 item to the NEWS file.
 168
 169 If you document your change in NEWS, please mark the NEWS entry with
 170 the documentation status of the change: if you submit the changes for
 171 the manuals, mark it with "+++"; if it doesn't need to be documented,
 172 mark it with "---"; if it needs to be documented, but you didn't
 173 submit documentation changes, leave the NEWS entry unmarked.  (These
 174 marks are checked by the Emacs maintainers to make sure every change
 175 was reflected in the manuals.)
 176
 177
 178 ** Understanding Emacs Internals.
 179
 180 The best way to understand Emacs Internals is to read the code,
 181 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 182 of the Emacs Lisp Reference Manual may also help.
 183
 184 The file etc/DEBUG describes how to debug Emacs bugs.
 185
 186
 187
 188 * How to Maintain Copyright Years for GNU Emacs
 189
 190 ** Our lawyer says it is ok if we add, to each file that has been in Emacs
 191 since Emacs 21 came out in 2001, all the subsequent years.  We don't
 192 need to check whether *that file* was changed in those years.
 193 It's sufficient that *Emacs* was changed in those years (and it was!).
 194
 195 ** For those files that have been added since then, we should add
 196 the year it was added to Emacs, and all subsequent years.
 197
 198 ** For the refcards under etc/, it's ok to simply use the latest year
 199 (typically in a `\def\year{YEAR}' expression) for the rendered copyright
 200 notice, while maintaining the full list of years in the copyright notice
 201 in the comments.
 202
 203 \f
 204 Local variables:
 205 mode: outline
 206 paragraph-separate: "[  \f]*$"
 207 end:
 208