CONTRIBUTE

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