Newer Older
This file contains information on Emacs developer processes.
Juri Linkov's avatar
Juri Linkov committed

3 4 5
For information on contributing to Emacs as a non-developer, see
(info "(emacs)Contributing") or
Juri Linkov's avatar
Juri Linkov committed

* Information for Emacs Developers.
Juri Linkov's avatar
Juri Linkov committed

An "Emacs Developer" is someone who contributes a lot of code or
10 11
documentation to the Emacs repository. Generally, they have write
access to the Emacs git repository on Savannah.
Juri Linkov's avatar
Juri Linkov committed

** Write access to the Emacs repository.
Juri Linkov's avatar
Juri Linkov committed

15 16 17
Once you become a frequent contributor to Emacs, we can consider
giving you write access to the version-control repository. Request
access on the mailing list.
Juri Linkov's avatar
Juri Linkov committed

** Using the Emacs repository
Juri Linkov's avatar
Juri Linkov committed

Emacs uses git for the source code repository.
Juri Linkov's avatar
Juri Linkov committed

23 24 25
See to get
started, and for more
advanced information.
Juri Linkov's avatar
Juri Linkov committed

Alternately, see admin/notes/git-workflow.
Juri Linkov's avatar
Juri Linkov committed

29 30 31 32
If committing changes written by someone else, make the ChangeLog
entry in their name, not yours. git distinguishes between the author
and the committer; use the --author option on the commit command to
specify the actual author; the committer defaults to you.
Juri Linkov's avatar
Juri Linkov committed

34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
** commit messages

When using git, commit messages should use ChangeLog format, with the
following modifications:

- Add a single short line explaining the change, then an empty line,
  then unindented ChangeLog entries.

  You can use various Emacs functions to ease this process; see (info
  "(emacs)Change Log Commands") or

- The summary line is limited to 72 characters (enforced by a commit
  hook). If you have trouble making that a good summary, add a
  paragraph below it, before the individual file descriptions.

- If only a single file is changed, the summary line can be the normal
  file first line (starting with the asterisk).  Then there is no
  individual files section.

- Explaining the rationale for a design choice is best done in comments
  in the source code. However, sometimes it is useful to describe just
  the rationale for a change; that can be done in the commit message
  between the summary line and the file entries.

59 60 61 62 63 64 65 66 67
** Changelog notes

- Emacs generally follows the GNU coding standards when it comes to
  ChangeLogs: .  One
  exception is that we still sometimes quote `like-this' (as the
  standards used to recommend) rather than 'like-this' (as they do
  now), because `...' is so widely used elsewhere in Emacs.

68 69 70 71 72 73 74 75 76 77 78
- Some of the rules in the GNU coding standards section 5.2
  "Commenting Your Work" also apply to Changelog entries: they must be
  in English, and be complete sentences starting with a capital and
  ending with a period (except the summary line should not end in a

  It is tempting to relax this rule for commit messages, since they
  are somewhat transient.  However, they are preserved indefinitely,
  and have a reasonable chance of being read in the future, so it's
  better that they have good presentation.

79 80 81 82 83
- There are multiple ChangeLogs in the emacs source; roughly one per
  high-level directory. The ChangeLog entry for a commit belongs in the
  lowest ChangeLog that is higher than or at the same level as any file
  changed by the commit.

84 85 86
- Use the present tense; describe "what the change does", not "what
  the change did".

87 88 89 90 91 92 93 94
- Preferred form for several entries with the same content:

   * help.el (view-lossage):
   * kmacro.el (kmacro-edit-lossage):
   * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.

  (Rather than anything involving "ditto" and suchlike.)

95 96 97 98 99 100 101
- If the commit fixes a bug, add a separate line

  Fixes: bug#NNNN

  where NNNN is the bug number.

- In ChangeLog entries, there is no standard or recommended way to
102 103 104 105 106 107 108 109
  identify revisions.

  One way to identify revisions is by quoting their summary line.
  Another is with an action stamp - an RFC3339 date followed by !
  followed by the committer's email - for example,
  "2014-01-16T05:43:35Z!". Often, "my previous commit"
  will suffice.

- There is no need to make separate ChangeLog entries for files such
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
  as NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration
  of files such as 'configure'.  "There is no need" means you don't
  have to, but you can if you want to.

** branches

Development normally takes places on the trunk.
Sometimes specialized features are developed on separate branches
before possibly being merged to the trunk.

Development is discussed on the emacs-devel mailing list.

Sometime before the release of a new major version of Emacs a "feature
freeze" is imposed on the trunk, to prepare for creating a release
branch.  No new features may be added to the trunk after this point,
until the release branch is created. This freeze is announced on the
emacs-devel mailing list, and not anywhere else.

129 130
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.

132 133
Announcements about the freeze (and other important events) are made
on the info-gnu-emacs mailing list.
134 135 136 137 138

If you are fixing a bug that exists in the current release, be sure to
commit it to the release branch; it will be merged to the master
branch later.

139 140 141 142 143 144
However, if you know that the change will be difficult to merge to the
trunk (eg because the trunk code has changed a lot), you can apply the
change to both trunk and branch yourself.  Indicate in the release
branch commit log that there is no need to merge the commit to the
trunk; start the commit message with "Backport:".  gitmerge.el will
then exclude that commit from the merge to trunk.
145 146 147

** Other process information
Juri Linkov's avatar
Juri Linkov committed

149 150
See all the files in admin/notes/* . In particular, see
admin/notes/newfile, see admin/notes/repo.
Juri Linkov's avatar
Juri Linkov committed

152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
*** git vs rename

git does not explicitly represent a file renaming; it uses a percent
changed heuristic to deduce that a file was renamed. So if you are
planning to make extensive changes to a file after renaming it (or
moving it to another directory), you should:

- create a feature branch

- commit the rename without any changes

- make other changes

- merge the feature branch to trunk, _not_ squashing the commits into
  one. The commit message on this merge should summarize the renames
  and all the changes.

Juri Linkov's avatar
Juri Linkov committed
169 170 171 172
** Emacs Mailing lists.

Discussion about Emacs development takes place on

173 174 175
Bug reports and fixes, feature requests and implementations should be
sent to, the bug/feature list.  This is coupled
to the tracker at .
Juri Linkov's avatar
Juri Linkov committed

177 178
You can subscribe to the mailing lists, or see the list archives,
by following links from .
Juri Linkov's avatar
Juri Linkov committed
179 180 181

** Document your changes.

Any change that matters to end-users should have an entry in etc/NEWS.
Juri Linkov's avatar
Juri Linkov committed

Glenn Morris's avatar
Glenn Morris committed
184 185 186 187
Think about whether your change requires updating the documentation
(both manuals and doc-strings).  If you know it does not, mark the NEWS
entry with "---".  If you know that *all* the necessary documentation
updates have been made, mark the entry with "+++". Otherwise do not mark it.
Juri Linkov's avatar
Juri Linkov committed
188 189 190 191 192 193 194 195 196 197 198 199 200

** Understanding Emacs Internals.

The best way to understand Emacs Internals is to read the code,
but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
of the Emacs Lisp Reference Manual may also help.

The file etc/DEBUG describes how to debug Emacs bugs.

This file is part of GNU Emacs.

GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
it under the terms of the GNU General Public License as published by
203 204
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
205 206 207 208 209 210 211

GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Emacs.  If not, see <>.
Juri Linkov's avatar
Juri Linkov committed
213 214 215 216 217
Local variables:
mode: outline
paragraph-separate: "[ 	]*$"