CONTRIBUTE

   1 This file contains information on Emacs developer processes.
   2
   3 For information on contributing to Emacs as a non-developer, see
   4 (info "(emacs)Contributing") or
   5 http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
   6
   7 * Information for Emacs Developers.
   8
   9 An "Emacs Developer" is someone who contributes a lot of code or
  10 documentation to the Emacs repository. Generally, they have write
  11 access to the Emacs git repository on Savannah
  12 https://savannah.gnu.org/git/?group=emacs.
  13
  14 ** Write access to the Emacs repository.
  15
  16 Once you become a frequent contributor to Emacs, we can consider
  17 giving you write access to the version-control repository. Request
  18 access on the emacs-devel@gnu.org mailing list.
  19
  20 ** Using the Emacs repository
  21
  22 Emacs uses git for the source code repository.
  23
  24 See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
  25 started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
  26 advanced information.
  27
  28 Alternately, see admin/notes/git-workflow.
  29
  30 If committing changes written by someone else, make the ChangeLog
  31 entry in their name, not yours. git distinguishes between the author
  32 and the committer; use the --author option on the commit command to
  33 specify the actual author; the committer defaults to you.
  34
  35 ** commit messages
  36
  37 When using git, commit messages should use ChangeLog format, with the
  38 following modifications:
  39
  40 - Add a single short line explaining the change, then an empty line,
  41   then unindented ChangeLog entries.
  42
  43   You can use various Emacs functions to ease this process; see (info
  44   "(emacs)Change Log Commands") or
  45   http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
  46
  47 - The summary line is limited to 72 characters (enforced by a commit
  48   hook). If you have trouble making that a good summary, add a
  49   paragraph below it, before the individual file descriptions.
  50
  51 - If only a single file is changed, the summary line can be the normal
  52   file first line (starting with the asterisk).  Then there is no
  53   individual files section.
  54
  55 - Explaining the rationale for a design choice is best done in comments
  56   in the source code. However, sometimes it is useful to describe just
  57   the rationale for a change; that can be done in the commit message
  58   between the summary line and the file entries.
  59
  60 ** ChangeLog notes
  61
  62 - Emacs generally follows the GNU coding standards when it comes to
  63   ChangeLogs:
  64   http://www.gnu.org/prep/standards/html_node/Change-Logs.html .  One
  65   exception is that we still sometimes quote `like-this' (as the
  66   standards used to recommend) rather than 'like-this' (as they do
  67   now), because `...' is so widely used elsewhere in Emacs.
  68
  69 - Some of the rules in the GNU coding standards section 5.2
  70   "Commenting Your Work" also apply to ChangeLog entries: they must be
  71   in English, and be complete sentences starting with a capital and
  72   ending with a period (except the summary line should not end in a
  73   period).
  74
  75   It is tempting to relax this rule for commit messages, since they
  76   are somewhat transient.  However, they are preserved indefinitely,
  77   and have a reasonable chance of being read in the future, so it's
  78   better that they have good presentation.
  79
  80 - There are multiple ChangeLogs in the emacs source; roughly one per
  81   high-level directory. The ChangeLog entry for a commit belongs in the
  82   lowest ChangeLog that is higher than or at the same level as any file
  83   changed by the commit.
  84
  85 - Use the present tense; describe "what the change does", not "what
  86   the change did".
  87
  88 - Preferred form for several entries with the same content:
  89
  90    * help.el (view-lossage):
  91    * kmacro.el (kmacro-edit-lossage):
  92    * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
  93
  94   (Rather than anything involving "ditto" and suchlike.)
  95
  96 - If the commit fixes a bug, add a separate line
  97
  98   Fixes: bug#NNNN
  99
 100   where NNNN is the bug number.
 101
 102 - In ChangeLog entries, there is no standard or recommended way to
 103   identify revisions.
 104
 105   One way to identify revisions is by quoting their summary line.
 106   Another is with an action stamp - an RFC3339 date followed by !
 107   followed by the committer's email - for example,
 108   "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
 109   will suffice.
 110
 111 - There is no need to make separate ChangeLog entries for files such
 112   as NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration
 113   of files such as 'configure'.  "There is no need" means you don't
 114   have to, but you can if you want to.
 115
 116 ** branches
 117
 118 Development normally takes places on the trunk.
 119 Sometimes specialized features are developed on separate branches
 120 before possibly being merged to the trunk.
 121
 122 Development is discussed on the emacs-devel mailing list.
 123
 124 Sometime before the release of a new major version of Emacs a "feature
 125 freeze" is imposed on the trunk, to prepare for creating a release
 126 branch.  No new features may be added to the trunk after this point,
 127 until the release branch is created. Announcements about the freeze
 128 (and other important events) are made on the info-gnu-emacs mailing
 129 list, and not anywhere else.
 130
 131 The trunk branch is named "master" in git; release branches are named
 132 "emacs-nn" where "nn" is the major version.
 133
 134 If you are fixing a bug that exists in the current release, be sure to
 135 commit it to the release branch; it will be merged to the master
 136 branch later.
 137
 138 However, if you know that the change will be difficult to merge to the
 139 trunk (eg because the trunk code has changed a lot), you can apply the
 140 change to both trunk and branch yourself.  Indicate in the release
 141 branch commit log that there is no need to merge the commit to the
 142 trunk; start the commit message with "Backport:".  gitmerge.el will
 143 then exclude that commit from the merge to trunk.
 144
 145
 146 ** Other process information
 147
 148 See all the files in admin/notes/* . In particular, see
 149 admin/notes/newfile, see admin/notes/repo.
 150
 151 *** git vs rename
 152
 153 git does not explicitly represent a file renaming; it uses a percent
 154 changed heuristic to deduce that a file was renamed. So if you are
 155 planning to make extensive changes to a file after renaming it (or
 156 moving it to another directory), you should:
 157
 158 - create a feature branch
 159
 160 - commit the rename without any changes
 161
 162 - make other changes
 163
 164 - merge the feature branch to trunk, _not_ squashing the commits into
 165   one. The commit message on this merge should summarize the renames
 166   and all the changes.
 167
 168 ** Emacs Mailing lists.
 169
 170 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 171
 172 Bug reports and fixes, feature requests and implementations should be
 173 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
 174 to the tracker at http://debbugs.gnu.org .
 175
 176 You can subscribe to the mailing lists, or see the list archives,
 177 by following links from http://savannah.gnu.org/mail/?group=emacs .
 178
 179 ** Document your changes.
 180
 181 Any change that matters to end-users should have an entry in etc/NEWS.
 182
 183 Doc-strings should be updated together with the code.
 184
 185 Think about whether your change requires updating the manuals.  If you
 186 know it does not, mark the NEWS entry with "---".  If you know
 187 that *all* the necessary documentation updates have been made, mark
 188 the entry with "+++". Otherwise do not mark it.
 189
 190 ** Understanding Emacs Internals.
 191
 192 The best way to understand Emacs Internals is to read the code,
 193 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 194 of the Emacs Lisp Reference Manual may also help.
 195
 196 The file etc/DEBUG describes how to debug Emacs bugs.
 197
 198
 199 \f
 200 This file is part of GNU Emacs.
 201
 202 GNU Emacs is free software: you can redistribute it and/or modify
 203 it under the terms of the GNU General Public License as published by
 204 the Free Software Foundation, either version 3 of the License, or
 205 (at your option) any later version.
 206
 207 GNU Emacs is distributed in the hope that it will be useful,
 208 but WITHOUT ANY WARRANTY; without even the implied warranty of
 209 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 210 GNU General Public License for more details.
 211
 212 You should have received a copy of the GNU General Public License
 213 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 214 \f
 215 Local variables:
 216 mode: outline
 217 paragraph-separate: "[  \f]*$"
 218 end: