etc/CONTRIBUTE

   1 Copyright (C) 2006, 2007, 2008, 2009, 2010
   2   Free Software Foundation, Inc.
   3 See end for license conditions.
   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 Standards.
  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/
  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 (roughly, fewer than 15 lines) without
  49 legal papers.  Anything more substantial requires a copyright
  50 disclaimer or assignment (the latter is preferred, especially for
  51 larger changes).  Both of these involved filling out a short form and
  52 filing it with the FSF.  The process is straightforward -- contact us
  53 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 Bazaar from the
  59 Savannah web site.  It is important to write your patch based on the
  60 latest version.  If you start from an older version, your patch may be
  61 outdated (so that maintainers will have a hard time applying it), or
  62 changes in Emacs may have made your patch unnecessary.
  63
  64 After you have downloaded the Bazaar source, you should read the file
  65 INSTALL.BZR 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 bug-gnu-emacs@gnu.org or emacs-devel@gnu.org.
  78
  79 All subsequent discussion should be sent to the same 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 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 Bazaar repository, make sure your copy is
 104 up-to-date (e.g. with `bzr pull'), then use
 105         bzr diff --no-aliases --diff-options=-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 ** Do not make formatting changes.
 128
 129 Making cosmetic formatting changes (indentation, etc) makes it harder
 130 to see what you have really changed.
 131
 132
 133 * Coding style and conventions.
 134
 135 ** Mandatory reading:
 136
 137 The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
 138
 139 ** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
 140 included in Emacs.
 141
 142 ** Remove all trailing whitespace in all source and text files.
 143
 144 ** Use ?\s instead of ?  in Lisp code for a space character.
 145
 146
 147 * Supplemental information for Emacs Developers.
 148
 149 ** Write access to the Emacs repository.
 150
 151 Once you become a frequent contributor to Emacs, we can consider
 152 giving you write access to the Bazaar repository.
 153
 154
 155 ** Emacs Mailing lists.
 156
 157 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 158
 159 Bug reports and feature requests are sent to bug-gnu-emacs@gnu.org.
 160
 161 You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
 162
 163 You can find the mailing lists archives at lists.gnu.org or gmane.org.
 164
 165
 166 ** Document your changes.
 167
 168 Think carefully about whether your change requires updating the
 169 documentation.  If it does, you can either do this yourself or add an
 170 item to the NEWS file.
 171
 172 If you document your change in NEWS, please mark the NEWS entry with
 173 the documentation status of the change: if you submit the changes for
 174 the manuals, mark it with "+++"; if it doesn't need to be documented,
 175 mark it with "---"; if it needs to be documented, but you didn't
 176 submit documentation changes, leave the NEWS entry unmarked.  (These
 177 marks are checked by the Emacs maintainers to make sure every change
 178 was reflected in the manuals.)
 179
 180
 181 ** Understanding Emacs Internals.
 182
 183 The best way to understand Emacs Internals is to read the code,
 184 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 185 of the Emacs Lisp Reference Manual may also help.
 186
 187 The file etc/DEBUG describes how to debug Emacs bugs.
 188
 189
 190 \f
 191 This file is part of GNU Emacs.
 192
 193 GNU Emacs is free software: you can redistribute it and/or modify
 194 it under the terms of the GNU General Public License as published by
 195 the Free Software Foundation, either version 3 of the License, or
 196 (at your option) any later version.
 197
 198 GNU Emacs is distributed in the hope that it will be useful,
 199 but WITHOUT ANY WARRANTY; without even the implied warranty of
 200 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 201 GNU General Public License for more details.
 202
 203 You should have received a copy of the GNU General Public License
 204 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 205 \f
 206 Local variables:
 207 mode: outline
 208 paragraph-separate: "[  \f]*$"
 209 end:
 210