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.  Also, be sure to
  19 subscribe to the emacs-devel@gnu.org mailing list and include the
  20 "emacs-announce" topic, so that you get the announcements about
  21 feature freeze and other important events.
  22
  23 ** Using the Emacs repository
  24
  25 Emacs uses Git for the source code repository.
  26
  27 See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
  28 started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
  29 advanced information.
  30
  31 Alternately, see admin/notes/git-workflow.
  32
  33 If committing changes written by someone else, make the commit in
  34 their name, not yours.  Git distinguishes between the author
  35 and the committer; use the --author option on the commit command to
  36 specify the actual author; the committer defaults to you.
  37
  38 ** Commit messages
  39
  40 Emacs development no longer stores descriptions of new changes in
  41 ChangeLog files.  Instead, a single ChangeLog file is generated from
  42 the commit messages when a release is prepared.  So changes you commit
  43 should not touch any of the ChangeLog files in the repository, but
  44 instead should contain the log entries in the commit message.  Here is
  45 an example of a commit message (indented):
  46
  47         Deactivate shifted region
  48
  49         Do not silently extend a region that is not highlighted;
  50         this can happen after a shift (Bug#19003).
  51         * doc/emacs/mark.texi (Shift Selection): Document the change.
  52         * lisp/window.el (handle-select-window):
  53         * src/frame.c (Fhandle_switch_frame, Fselected_frame):
  54         Deactivate the mark.
  55
  56 Below are some rules and recommendations for formatting commit
  57 messages:
  58
  59 - Start with a single unindented summary line explaining the change;
  60   do not end this line with a period.  If that line starts with a
  61   semi-colon and a space "; ", the log message will be ignored when
  62   generating the ChangeLog file.  Use this for minor commits that do
  63   not need separate ChangeLog entries, such as changes in etc/NEWS.
  64
  65 - After the summary line, there should be an empty line, then
  66   unindented ChangeLog entries.
  67
  68 - Limit lines in commit messages to 78 characters, unless they consist
  69   of a single word of at most 140 characters; this is enforced by a
  70   commit hook.  It's nicer to limit the summary line to 50 characters;
  71   this isn't enforced.  If the change can't be summarized so briefly,
  72   add a paragraph after the empty line and before the individual file
  73   descriptions.
  74
  75 - If only a single file is changed, the summary line can be the normal
  76   file first line (starting with the asterisk).  Then there is no
  77   individual files section.
  78
  79 - If the commit has more than one author, the commit message should
  80   contain separate lines to mention the other authors, like the
  81   following:
  82
  83         Co-authored-by: Joe Schmoe <j.schmoe@example.org>
  84
  85 - If the commit is a tiny change that is exempt from copyright paperwork,
  86   the commit message should contain a separate line like the following:
  87
  88         Copyright-paperwork-exempt: yes
  89
  90 - The commit message should contain "Bug#NNNNN" if it is related to
  91   bug number NNNNN in the debbugs database.  This string is often
  92   parenthesized, as in "(Bug#19003)".
  93
  94 - Commit messages should contain only printable UTF-8 characters.
  95
  96 - Commit messages should not contain the "Signed-off-by:" lines that
  97   are used in some other projects.
  98
  99 - Any lines of the commit message that start with "; " are omitted
 100   from the generated ChangeLog.
 101
 102 - Explaining the rationale for a design choice is best done in comments
 103   in the source code.  However, sometimes it is useful to describe just
 104   the rationale for a change; that can be done in the commit message
 105   between the summary line and the file entries.
 106
 107 - Emacs generally follows the GNU coding standards when it comes to
 108   ChangeLogs:
 109   http://www.gnu.org/prep/standards/html_node/Change-Logs.html or
 110   "(info (standards)Change Logs").  One exception is that we still
 111   sometimes quote `like-this' (as the standards used to recommend)
 112   rather than 'like-this' (as they do now), because `...' is so widely
 113   used elsewhere in Emacs.
 114
 115 - Some of the rules in the GNU coding standards section 5.2
 116   "Commenting Your Work" also apply to ChangeLog entries: they must be
 117   in English, and be complete sentences starting with a capital and
 118   ending with a period (except the summary line should not end in a
 119   period).
 120
 121   They are preserved indefinitely, and have a reasonable chance of
 122   being read in the future, so it's better that they have good
 123   presentation.
 124
 125 - Use the present tense; describe "what the change does", not "what
 126   the change did".
 127
 128 - Preferred form for several entries with the same content:
 129
 130         * lisp/help.el (view-lossage):
 131         * lisp/kmacro.el (kmacro-edit-lossage):
 132         * lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
 133
 134   (Rather than anything involving "ditto" and suchlike.)
 135
 136 - There is no standard or recommended way to identify revisions in
 137   ChangeLog entries.  Using Git SHA1 values limits the usability of
 138   the references to Git, and will become much less useful if Emacs
 139   switches to a different VCS.  So we recommend against that.
 140
 141   One way to identify revisions is by quoting their summary line.
 142   Another is with an action stamp - an RFC3339 date followed by !
 143   followed by the committer's email - for example,
 144   "2014-01-16T05:43:35Z!esr@thyrsus.com".  Often, "my previous commit"
 145   will suffice.
 146
 147 - There is no need to mention files such as NEWS, MAINTAINERS, and
 148   FOR-RELEASE, or to indicate regeneration of files such as
 149   'configure', in the ChangeLog entry.  "There is no need" means you
 150   don't have to, but you can if you want to.
 151
 152 ** Generating ChangeLog entries
 153
 154 - You can use various Emacs functions to ease the process of writing
 155   ChangeLog entries; see (info "(emacs)Change Log Commands") or
 156   http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
 157
 158 - If you use Emacs VC, one way to format ChangeLog entries is to create
 159   a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
 160   usual.  Do not register the ChangeLog file under git; instead, use
 161   'C-c C-a' to insert its contents into into your *vc-log* buffer.
 162   Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
 163   does by default), they will be filled in for you automatically.
 164
 165 - Alternatively, you can use the vc-dwim command to maintain commit
 166   messages.  When you create a source directory, run the shell command
 167   'git-changelog-symlink-init' to create a symbolic link from
 168   ChangeLog to .git/c/ChangeLog.  Edit this ChangeLog via its symlink
 169   with Emacs commands like 'C-x 4 a', and commit the change using the
 170   shell command 'vc-dwim --commit'.  Type 'vc-dwim --help' for more.
 171
 172 ** Branches
 173
 174 Development normally takes places on the trunk.
 175 Sometimes specialized features are developed on separate branches
 176 before possibly being merged to the trunk.
 177
 178 Development is discussed on the emacs-devel mailing list.
 179
 180 Sometime before the release of a new major version of Emacs a "feature
 181 freeze" is imposed on the trunk, to prepare for creating a release
 182 branch.  No new features may be added to the trunk after this point,
 183 until the release branch is created.  Announcements about the freeze
 184 (and other important events) are made on the emacs-devel mailing
 185 list under the "emacs-announce" topic, and not anywhere else.
 186
 187 The trunk branch is named "master" in git; release branches are named
 188 "emacs-nn" where "nn" is the major version.
 189
 190 If you are fixing a bug that exists in the current release, be sure to
 191 commit it to the release branch; it will be merged to the master
 192 branch later.
 193
 194 However, if you know that the change will be difficult to merge to the
 195 trunk (eg because the trunk code has changed a lot), you can apply the
 196 change to both trunk and branch yourself.  Indicate in the release
 197 branch commit log that there is no need to merge the commit to the
 198 trunk; start the commit message with "Backport:".  gitmerge.el will
 199 then exclude that commit from the merge to trunk.
 200
 201
 202 ** Other process information
 203
 204 See all the files in admin/notes/* .  In particular, see
 205 admin/notes/newfile, see admin/notes/repo.
 206
 207 *** git vs rename
 208
 209 Git does not explicitly represent a file renaming; it uses a percent
 210 changed heuristic to deduce that a file was renamed.  So if you are
 211 planning to make extensive changes to a file after renaming it (or
 212 moving it to another directory), you should:
 213
 214 - create a feature branch
 215
 216 - commit the rename without any changes
 217
 218 - make other changes
 219
 220 - merge the feature branch to trunk, _not_ squashing the commits into
 221   one.  The commit message on this merge should summarize the renames
 222   and all the changes.
 223
 224 ** Emacs Mailing lists.
 225
 226 Discussion about Emacs development takes place on emacs-devel@gnu.org.
 227
 228 Bug reports and fixes, feature requests and implementations should be
 229 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
 230 to the tracker at http://debbugs.gnu.org .
 231
 232 You can subscribe to the mailing lists, or see the list archives,
 233 by following links from http://savannah.gnu.org/mail/?group=emacs .
 234
 235 To email a patch you can use a shell command like 'git format-patch -1'
 236 to create a file, and then attach the file to your email.  This nicely
 237 packages the patch's commit message and changes.
 238
 239 ** Document your changes.
 240
 241 Any change that matters to end-users should have an entry in etc/NEWS.
 242
 243 Doc-strings should be updated together with the code.
 244
 245 Think about whether your change requires updating the manuals.  If you
 246 know it does not, mark the NEWS entry with "---".  If you know
 247 that *all* the necessary documentation updates have been made, mark
 248 the entry with "+++".  Otherwise do not mark it.
 249
 250 Please see (info "(elisp)Documentation Tips") or
 251 https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
 252 for more specific tips on Emacs's doc style.  Use 'checkdoc' to check
 253 for documentation errors before submitting a patch.
 254
 255 ** Test your changes.
 256
 257 Please test your changes before committing them or sending them to the
 258 list.
 259
 260 Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
 261 "(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
 262 for more information on writing and running tests.
 263
 264 To run tests on the entire Emacs tree, run "make check" from the
 265 top-level directory.  Most tests are in the directory
 266 "test/automated".  From the "test/automated" directory, run "make
 267 <filename>" to run the tests for <filename>.el(c).  See
 268 "test/automated/Makefile" for more information.
 269
 270 ** Understanding Emacs Internals.
 271
 272 The best way to understand Emacs Internals is to read the code,
 273 but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
 274 of the Emacs Lisp Reference Manual may also help.  Some source files,
 275 such as xdisp.c, have large commentaries describing the design and
 276 implementation in more detail.
 277
 278 The file etc/DEBUG describes how to debug Emacs bugs.
 279
 280
 281 \f
 282 This file is part of GNU Emacs.
 283
 284 GNU Emacs is free software: you can redistribute it and/or modify
 285 it under the terms of the GNU General Public License as published by
 286 the Free Software Foundation, either version 3 of the License, or
 287 (at your option) any later version.
 288
 289 GNU Emacs is distributed in the hope that it will be useful,
 290 but WITHOUT ANY WARRANTY; without even the implied warranty of
 291 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 292 GNU General Public License for more details.
 293
 294 You should have received a copy of the GNU General Public License
 295 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 296 \f
 297 Local variables:
 298 mode: outline
 299 paragraph-separate: "[  \f]*$"
 300 end: