CONTRIBUTE 13.6 KB
Newer Older
1
This file contains information on Emacs developer processes.
Juri Linkov's avatar
Juri Linkov committed
2

3 4 5
For information on contributing to Emacs as a non-developer, see
(info "(emacs)Contributing") or
http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
Juri Linkov's avatar
Juri Linkov committed
6

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

9
An "Emacs Developer" is someone who contributes a lot of code or
Eli Zaretskii's avatar
Eli Zaretskii committed
10
documentation to the Emacs repository.  Generally, they have write
11 12
access to the Emacs git repository on Savannah
https://savannah.gnu.org/git/?group=emacs.
Juri Linkov's avatar
Juri Linkov committed
13

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

16
Once you become a frequent contributor to Emacs, we can consider
Eli Zaretskii's avatar
Eli Zaretskii committed
17 18 19 20 21
giving you write access to the version-control repository.  Request
access on the emacs-devel@gnu.org mailing list.  Also, be sure to
subscribe to the emacs-devel@gnu.org mailing list and include the
"emacs-announce" topic, so that you get the announcements about
feature freeze and other important events.
Juri Linkov's avatar
Juri Linkov committed
22

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

Eli Zaretskii's avatar
Eli Zaretskii committed
25
Emacs uses Git for the source code repository.
Juri Linkov's avatar
Juri Linkov committed
26

27 28 29
See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
advanced information.
Juri Linkov's avatar
Juri Linkov committed
30

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

33
If committing changes written by someone else, make the commit in
Eli Zaretskii's avatar
Eli Zaretskii committed
34
their name, not yours.  Git distinguishes between the author
35 36
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
37

38
** Commit messages
39

Eli Zaretskii's avatar
Eli Zaretskii committed
40 41 42 43 44 45
Emacs development no longer stores descriptions of new changes in
ChangeLog files.  Instead, a single ChangeLog file is generated from
the commit messages when a release is prepared.  So changes you commit
should not touch any of the ChangeLog files in the repository, but
instead should contain the log entries in the commit message.  Here is
an example of a commit message (indented):
46 47 48 49

	Deactivate shifted region

	Do not silently extend a region that is not highlighted;
50
	this can happen after a shift (Bug#19003).
51 52 53 54 55
	* doc/emacs/mark.texi (Shift Selection): Document the change.
	* lisp/window.el (handle-select-window):
	* src/frame.c (Fhandle_switch_frame, Fselected_frame):
	Deactivate the mark.

Eli Zaretskii's avatar
Eli Zaretskii committed
56 57
Below are some rules and recommendations for formatting commit
messages:
58

Eli Zaretskii's avatar
Eli Zaretskii committed
59 60 61 62 63 64 65 66
- Start with a single unindented summary line explaining the change;
  do not end this line with a period.  If that line starts with a
  semi-colon and a space "; ", the log message will be ignored when
  generating the ChangeLog file.  Use this for minor commits that do
  not need separate ChangeLog entries, such as changes in etc/NEWS.

- After the summary line, there should be an empty line, then
  unindented ChangeLog entries.
67

68
- Limit lines in commit messages to 78 characters, unless they consist
69 70 71 72 73
  of a single word of at most 140 characters; this is enforced by a
  commit hook.  It's nicer to limit the summary line to 50 characters;
  this isn't enforced.  If the change can't be summarized so briefly,
  add a paragraph after the empty line and before the individual file
  descriptions.
74 75 76 77 78

- 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.

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:
Eli Zaretskii's avatar
Eli Zaretskii committed
82 83 84 85 86 87 88 89 90 91 92

	Co-authored-by: Joe Schmoe <j.schmoe@example.org>

- If the commit is a tiny change that is exempt from copyright paperwork,
  the commit message should contain a separate line like the following:

	Copyright-paperwork-exempt: yes

- The commit message should contain "Bug#NNNNN" if it is related to
  bug number NNNNN in the debbugs database.  This string is often
  parenthesized, as in "(Bug#19003)".
93

94 95
- Commit messages should contain only printable UTF-8 characters.

Paul Eggert's avatar
Paul Eggert committed
96
- Commit messages should not contain the "Signed-off-by:" lines that
97 98
  are used in some other projects.

99
- Any lines of the commit message that start with "; " are omitted
100 101
  from the generated ChangeLog.

Eli Zaretskii's avatar
Eli Zaretskii committed
102 103 104 105 106
- 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.

107 108
- Emacs generally follows the GNU coding standards when it comes to
  ChangeLogs:
Eli Zaretskii's avatar
Eli Zaretskii committed
109 110 111 112 113
  http://www.gnu.org/prep/standards/html_node/Change-Logs.html or
  "(info (standards)Change Logs").  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.
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 118 119 120
  in English, and be complete sentences starting with a capital and
  ending with a period (except the summary line should not end in a
  period).

121 122 123
  They are preserved indefinitely, and have a reasonable chance of
  being read in the future, so it's better that they have good
  presentation.
124 125 126 127

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

128 129
- Preferred form for several entries with the same content:

130 131 132
	* lisp/help.el (view-lossage):
	* lisp/kmacro.el (kmacro-edit-lossage):
	* lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
133 134 135

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

Eli Zaretskii's avatar
Eli Zaretskii committed
136 137 138 139
- There is no standard or recommended way to identify revisions in
  ChangeLog entries.  Using Git SHA1 values limits the usability of
  the references to Git, and will become much less useful if Emacs
  switches to a different VCS.  So we recommend against that.
140 141 142 143

  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,
Eli Zaretskii's avatar
Eli Zaretskii committed
144
  "2014-01-16T05:43:35Z!esr@thyrsus.com".  Often, "my previous commit"
145 146
  will suffice.

147 148 149 150
- There is no need to mention files such as NEWS and MAINTAINERS, or
  to indicate regeneration of files such as 'configure', in the
  ChangeLog entry.  "There is no need" means you don't have to, but
  you can if you want to.
151

152 153 154 155 156 157 158
** Generating ChangeLog entries

- You can use various Emacs functions to ease the process of writing
  ChangeLog entries; see (info "(emacs)Change Log Commands") or
  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.

- 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 161
  usual.  Do not register the ChangeLog file under git; instead, use
  '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 166 167 168 169 170 171

- Alternatively, you can use the vc-dwim command to maintain commit
  messages.  When you create a source directory, run the shell command
  'git-changelog-symlink-init' to create a symbolic link from
  ChangeLog to .git/c/ChangeLog.  Edit this ChangeLog via its symlink
  with Emacs commands like 'C-x 4 a', and commit the change using the
  shell command 'vc-dwim --commit'.  Type 'vc-dwim --help' for more.

Eli Zaretskii's avatar
Eli Zaretskii committed
172
** Branches
173 174 175 176 177 178 179

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.

180 181
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
182 183 184 185 186

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.

187 188
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
189 190 191 192 193 194
change to both trunk and branch yourself.  It could also happen that a
change is cherry-picked from master to the release branch, and so
doesn't need to be merged back.  In these cases, 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.
195 196 197


** Other process information
Juri Linkov's avatar
Juri Linkov committed
198 199 200 201 202

** Emacs Mailing lists.

Discussion about Emacs development takes place on emacs-devel@gnu.org.

203 204 205
Bug reports and fixes, feature requests and implementations should be
sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
to the tracker at http://debbugs.gnu.org .
Juri Linkov's avatar
Juri Linkov committed
206

207 208
You can subscribe to the mailing lists, or see the list archives,
by following links from http://savannah.gnu.org/mail/?group=emacs .
Juri Linkov's avatar
Juri Linkov committed
209

210 211
To email a patch you can use a shell command like 'git format-patch -1'
to create a file, and then attach the file to your email.  This nicely
212 213 214
packages the patch's commit message and changes.  To send just one
such patch without additional remarks, you can use a command like
'git send-email --to=bug-gnu-emacs@gnu.org 0001-DESCRIPTION.patch'.
215

216 217 218 219 220 221 222 223 224 225 226
** Issue tracker (a.k.a. "bug tracker")

The Emacs issue tracker is at http://debbugs.gnu.org/.  The form
presented by that page allows to view bug reports and search the
database for bugs matching several criteria.  Messages posted to the
bug-gnu-emacs@gnu.org mailing list, mentioned above, are recorded by
the tracker with the corresponding bugs/issues.

GNU ELPA has a 'debbugs' package that allows accessing the tracker
database from Emacs.

Juri Linkov's avatar
Juri Linkov committed
227 228
** Document your changes.

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

231 232 233 234 235
Doc-strings should be updated together with the code.

Think about whether your change requires updating the manuals.  If you
know it does not, mark the NEWS entry with "---".  If you know
that *all* the necessary documentation updates have been made, mark
Eli Zaretskii's avatar
Eli Zaretskii committed
236
the entry with "+++".  Otherwise do not mark it.
Juri Linkov's avatar
Juri Linkov committed
237

238 239
Please see (info "(elisp)Documentation Tips") or
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
240
for more specific tips on Emacs's doc style.  Use 'checkdoc' to check
241 242 243 244 245
for documentation errors before submitting a patch.

** Test your changes.

Please test your changes before committing them or sending them to the
246 247 248
list.  If possible, add a new test along with any bug fix or new
functionality you commit (of course, some changes cannot be easily
tested).
249 250 251 252 253

Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
"(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
for more information on writing and running tests.

254
If your test lasts longer than some few seconds, mark it in its
255
'ert-deftest' definition with ":tags '(:expensive-test)".
256

257 258 259
To run tests on the entire Emacs tree, run "make check" from the
top-level directory.  Most tests are in the directory
"test/automated".  From the "test/automated" directory, run "make
260 261
<filename>" to run the tests for <filename>.el(c).  See "test/README"
for more information.
262

Juri Linkov's avatar
Juri Linkov committed
263 264 265 266
** 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
Eli Zaretskii's avatar
Eli Zaretskii committed
267 268 269
of the Emacs Lisp Reference Manual may also help.  Some source files,
such as xdisp.c, have large commentaries describing the design and
implementation in more detail.
Juri Linkov's avatar
Juri Linkov committed
270 271 272

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

273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
*** Non-ASCII characters in Emacs files

If you introduce non-ASCII characters into Emacs source files, it is a
good idea to add a 'coding' cookie to the file to state its encoding.
Please use the UTF-8 encoding unless it cannot do the job for some
good reason.  As of Emacs 24.4, it is no longer necessary to have
explicit 'coding' cookies in *.el files if they are encoded in UTF-8,
but other files need them even if encoded in UTF-8.  However, if
an *.el file is intended for use with older Emacs versions (e.g. if
it's also distributed via ELPA), having an explicit encoding
specification is still a good idea.

*** Useful files in the admin/ directory

See all the files in admin/notes/* .  In particular, see
admin/notes/newfile, see admin/notes/repo.

The file admin/MAINTAINERS records the areas of interest of frequent
Emacs contributors.  If you are making changes in one of the files
mentioned there, it is a good idea to consult the person who expressed
an interest in that file, and/or get his/her feedback for the changes.
If you are a frequent contributor and have interest in maintaining
specific files, please record those interests in that file, so that
others could be aware of that.

*** 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
315 316 317 318


This file is part of GNU Emacs.

319
GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
320
it under the terms of the GNU General Public License as published by
321 322
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
323 324 325 326 327 328 329

GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
330
along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Juri Linkov's avatar
Juri Linkov committed
331 332 333 334 335

Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
end: