CONTRIBUTE 18.2 KB
Newer Older
Paul Eggert's avatar
Paul Eggert committed
1
* How developers contribute to GNU Emacs
Juri Linkov's avatar
Juri Linkov committed
2

Paul Eggert's avatar
Paul Eggert committed
3
Here is how software developers can contribute to Emacs.  (Non-developers: see
4
https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
Paul Eggert's avatar
Paul Eggert committed
5
or run the shell command 'info "(emacs)Contributing"'.)
Juri Linkov's avatar
Juri Linkov committed
6

Paul Eggert's avatar
Paul Eggert committed
7
** The Emacs repository
Juri Linkov's avatar
Juri Linkov committed
8

Paul Eggert's avatar
Paul Eggert committed
9
Emacs development uses Git on Savannah for its main repository.
10
To configure Git for Emacs development, you can run the following:
Juri Linkov's avatar
Juri Linkov committed
11

Paul Eggert's avatar
Paul Eggert committed
12 13 14
	git config --global user.name 'Your Name'
	git config --global user.email 'your.name@example.com'
	git config --global transfer.fsckObjects true
15 16 17

The following shell commands then build and run Emacs from scratch:

Paul Eggert's avatar
Paul Eggert committed
18 19
	git clone git://git.sv.gnu.org/emacs.git
	cd emacs
Paul Eggert's avatar
Paul Eggert committed
20
	./autogen.sh
Paul Eggert's avatar
Paul Eggert committed
21 22 23
	./configure
	make
	src/emacs
Juri Linkov's avatar
Juri Linkov committed
24

Paul Eggert's avatar
Paul Eggert committed
25
For more details, see
Paul Eggert's avatar
Paul Eggert committed
26 27
https://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
https://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
Paul Eggert's avatar
Paul Eggert committed
28
admin/notes/git-workflow.
Juri Linkov's avatar
Juri Linkov committed
29

Paul Eggert's avatar
Paul Eggert committed
30
** Getting involved with development
Juri Linkov's avatar
Juri Linkov committed
31

32
Discussion about Emacs development takes place on emacs-devel@gnu.org.
33 34 35 36 37
You can subscribe to the emacs-devel@gnu.org mailing list.
If you want to get only the important mails (for things like
feature freezes), choose to receive only the 'emacs-announce' topic
(although so far this feature has not been well or consistently used).
See https://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list
Paul Eggert's avatar
Paul Eggert committed
38 39 40 41
instructions and archives.  You can develop and commit changes in your
own copy of the repository, and discuss proposed changes on the
mailing list.  Frequent contributors to Emacs can request write access
there.
Juri Linkov's avatar
Juri Linkov committed
42

43 44
Bug reports and fixes, feature requests and patches/implementations
should be sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This
45
is coupled to the https://debbugs.gnu.org tracker.  It is best to use
46 47 48
the command 'M-x report-emacs-bug RET' to report issues to the tracker
(described below).  Be prepared to receive comments and requests for
changes in your patches, following your submission.
Juri Linkov's avatar
Juri Linkov committed
49

50
The Savannah info page https://savannah.gnu.org/mail/?group=emacs
51 52 53 54 55
describes how to subscribe to the mailing lists, or see the list
archives.

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
56 57 58 59 60 61 62 63 64 65 66 67
packages the patch's commit message and changes, and makes sure the
format and whitespace are not munged in transit by the various mail
agents.  To send just one such patch without additional remarks, it is
also possible to use a command like

  git send-email --to=bug-gnu-emacs@gnu.org 0001-DESCRIPTION.patch'.

However, we prefer the 'git format-patch' method with attachment, as
doing so delivers patches in the correct and easily-recognizable format
more reliably, and makes the job of applying the patches easier and less
error-prone.  It also allows to send patches whose author is someone
other than the email sender.
68

69 70 71 72 73 74
Once the cumulative amount of your submissions exceeds about 15 lines
of non-trivial changes, we will need you to assign to the FSF the
copyright for your contributions.  Ask on emacs-devel@gnu.org, and we
will send you the necessary form together with the instructions to
fill and email it, in order to start this legal paperwork.

75 76
** Issue tracker (a.k.a. "bug tracker")

77
The Emacs issue tracker at https://debbugs.gnu.org lets you view bug
78 79
reports and search the database for bugs matching several criteria.
Messages posted to the bug-gnu-emacs@gnu.org mailing list, mentioned
80 81 82 83
above, are recorded by the tracker with the corresponding
bugs/issues.  If a message to the bug tracker contains a patch, please
include the string "[PATCH]" in the subject of the message in order to
let the bug tracker tag the bug properly.
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101

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

Bugs needs regular attention.  A large backlog of bugs is
disheartening to the developers, and a culture of ignoring bugs is
harmful to users, who expect software that works.  Bugs have to be
regularly looked at and acted upon.  Not all bugs are critical, but at
the least, each bug needs to be regularly re-reviewed to make sure it
is still reproducible.

The process of going through old or new bugs and acting on them is
called bug triage.  This process is described in the file
admin/notes/bug-triage.

** Documenting your changes

Any change that matters to end-users should have an entry in etc/NEWS.
102 103 104
Try to start each NEWS entry with a sentence that summarizes the entry
and takes just one line -- this will allow to read NEWS in Outline
mode after hiding the body of each entry.
105 106 107

Doc-strings should be updated together with the code.

108 109 110 111
New defcustom's should always have a ':version' tag stating the first
Emacs version in which they will appear.  Likewise with defcustom's
whose value is changed -- update their ':version' tag.

112 113
Think about whether your change requires updating the manuals.  If you
know it does not, mark the NEWS entry with "---".  If you know
114 115 116
that *all* the necessary documentation updates have been made as part
of your changes or those by others, mark the entry with "+++".
Otherwise do not mark it.
117 118 119 120

If your change requires updating the manuals to document new
functions/commands/variables/faces, then use the proper Texinfo
command to index them; for instance, use @vindex for variables and
Eli Zaretskii's avatar
Eli Zaretskii committed
121
@findex for functions/commands.  For the full list of predefined indices, see
122
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
123 124
or run the shell command 'info "(texinfo)Predefined Indices"'.

125 126 127 128
We prefer American English both in doc strings and in the manuals.
That includes both spelling (e.g., "behavior", not "behaviour") and
the convention of leaving 2 spaces between sentences.

129
For more specific tips on Emacs's doc style, see
130
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
131 132 133 134 135 136 137 138 139 140
Use 'checkdoc' to check for documentation errors before submitting a patch.

** Testing your changes

Please test your changes before committing them or sending them to the
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).

Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See
141
https://www.gnu.org/software/emacs/manual/html_node/ert/
142
or run 'info "(ert)"' for more information on writing and running
143 144 145 146 147 148 149 150 151
tests.

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

To run tests on the entire Emacs tree, run "make check" from the
top-level directory.  Most tests are in the directory "test/".  From
the "test/" directory, run "make <filename>" to run the tests for
<filename>.el(c).  See "test/README" for more information.
Juri Linkov's avatar
Juri Linkov committed
152

153
** Commit messages
154

Paul Eggert's avatar
Paul Eggert committed
155 156 157
Ordinarily, a change you commit should contain a log entry in its
commit message and should not touch the repository's ChangeLog files.
Here is an example commit message (indented):
158 159 160 161

	Deactivate shifted region

	Do not silently extend a region that is not highlighted;
162
	this can happen after a shift (Bug#19003).
163 164 165 166 167
	* 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.

Paul Eggert's avatar
Paul Eggert committed
168 169 170
Occasionally, commit messages are collected and prepended to a
ChangeLog file, where they can be corrected.  It saves time to get
them right the first time, so here are guidelines for formatting them:
171

Eli Zaretskii's avatar
Eli Zaretskii committed
172 173
- Start with a single unindented summary line explaining the change;
  do not end this line with a period.  If that line starts with a
Paul Eggert's avatar
Paul Eggert committed
174
  semicolon and a space "; ", the commit message will be ignored when
Eli Zaretskii's avatar
Eli Zaretskii committed
175 176 177 178 179
  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.
180

181
- Limit lines in commit messages to 78 characters, unless they consist
182 183 184 185 186
  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.
187 188 189 190 191

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

192
- If the commit has more than one author, the commit message should
193
  contain separate lines to mention the other authors, like the
194
  following:
Eli Zaretskii's avatar
Eli Zaretskii committed
195 196 197 198 199 200 201 202 203 204 205

	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)".
206

207 208 209
- When citing URLs, prefer https: to http: when either will do.  In
  particular, gnu.org and fsf.org URLs should start with "https:".

210 211
- Commit messages should contain only printable UTF-8 characters.

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

215
- Any lines of the commit message that start with "; " are omitted
216 217
  from the generated ChangeLog.

Eli Zaretskii's avatar
Eli Zaretskii committed
218 219 220 221 222
- 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.

Paul Eggert's avatar
Paul Eggert committed
223
- Emacs generally follows the GNU coding standards for ChangeLogs: see
224
  https://www.gnu.org/prep/standards/html_node/Change-Logs.html
Paul Eggert's avatar
Paul Eggert committed
225 226 227 228
  or run 'info "(standards)Change Logs"'.  One exception is that
  commits still sometimes quote `like-this' (as the standards used to
  recommend) rather than 'like-this' or ‘like this’ (as they do now),
  as `...' is so widely used elsewhere in Emacs.
229

Paul Eggert's avatar
Paul Eggert committed
230 231 232 233
- Some commenting rules in the GNU coding standards 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 period).  See
234
  https://www.gnu.org/prep/standards/html_node/Comments.html
235
  or run 'info "(standards)Comments"'.  American English is preferred
236 237
  in Emacs; that includes spelling and leaving 2 blanks between
  sentences.
238

239 240 241
  They are preserved indefinitely, and have a reasonable chance of
  being read in the future, so it's better that they have good
  presentation.
242 243 244 245

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

246 247
- Preferred form for several entries with the same content:

248 249 250 251 252 253
	* lisp/menu-bar.el (clipboard-yank, clipboard-kill-ring-save)
	(clipboard-kill-region):
	* lisp/eshell/esh-io.el (eshell-virtual-targets)
	(eshell-clipboard-append):
	Replace option gui-select-enable-clipboard with
	select-enable-clipboard; renamed October 2014.  (Bug#25145)
254 255 256

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

Eli Zaretskii's avatar
Eli Zaretskii committed
257 258 259 260
- 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.
261 262 263 264

  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
265
  "2014-01-16T05:43:35Z!esr@thyrsus.com".  Often, "my previous commit"
266 267
  will suffice.

Xue Fuqiao's avatar
Xue Fuqiao committed
268
- There is no need to mention files such as NEWS and MAINTAINERS, or
Paul Eggert's avatar
Paul Eggert committed
269
  to indicate regeneration of files such as 'lib/gnulib.mk', in the
Xue Fuqiao's avatar
Xue Fuqiao committed
270 271
  ChangeLog entry.  "There is no need" means you don't have to, but
  you can if you want to.
272

273 274
** Generating ChangeLog entries

275 276 277 278 279
- If you use Emacs VC, you can use 'C-c C-w' to generate formatted
  blank ChangeLog entries from the diff being committed, then use
  'M-q' to combine and fill them.  See 'info "(emacs) Log Buffer"'.

- Alternatively, you can use Emacs functions for ChangeLog files; see
280
  https://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
Paul Eggert's avatar
Paul Eggert committed
281
  or run 'info "(emacs)Change Log Commands"'.
282

283 284 285 286 287 288
  To format ChangeLog entries with Emacs VC, create a top-level
  ChangeLog file manually, and update it with 'C-x 4 a' as usual.  Do
  not register the ChangeLog file under git; instead, use 'C-c C-a' to
  insert its contents into your *vc-log* buffer.  Or if
  'log-edit-hook' includes 'log-edit-insert-changelog' (which it does
  by default), they will be filled in for you automatically.
289

290
- Instead of Emacs VC, you can use the vc-dwim command to maintain commit
291 292 293 294 295 296
  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.

297 298 299 300 301 302
** Committing changes by others

If committing changes written by someone else, commit in their name,
not yours.  You can use 'git commit --author="AUTHOR"' to specify a
change's author.

Eli Zaretskii's avatar
Eli Zaretskii committed
303
** Branches
304

Paul Eggert's avatar
Paul Eggert committed
305 306 307 308 309 310 311 312
Future development normally takes place on the master branch.
Sometimes specialized features are developed on other branches before
possibly being merged to the master.  Release branches are named
"emacs-NN" where NN is the major version number, and are mainly
intended for more-conservative changes such as bug fixes.  Typically,
collective development is active on the master branch and possibly on
the current release branch.  Periodically, the current release branch
is merged into the master, using the gitmerge function described in
Eli Zaretskii's avatar
Eli Zaretskii committed
313
admin/notes/git-workflow.
314

315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
If you are fixing a bug that exists in the current release, you should
generally commit it to the release branch; it will be merged to the
master branch later by the gitmerge function.  However, when the
release branch is for Emacs version NN.2 and later, or when it is for
Emacs version NN.1 that is in the very last stages of its pretest,
that branch is considered to be in a feature freeze: only bug fixes
that are "safe" or are fixing major problems should go to the release
branch, the rest should be committed to the master branch.  This is so
to avoid destabilizing the next Emacs release.  If you are unsure
whether your bug fix is "safe" enough for the release branch, ask on
the emacs-devel mailing list.

Documentation fixes (in doc strings, in manuals, in NEWS, and in
comments) should always go to the release branch, if the documentation
to be fixed exists and is relevant to the release-branch codebase.
Doc fixes are always considered "safe" -- even when a release branch
is in feature freeze, it can still receive doc fixes.
Eli Zaretskii's avatar
Eli Zaretskii committed
332

333
When you know that the change will be difficult to merge to the
Paul Eggert's avatar
Paul Eggert committed
334
master (e.g., because the code on master has changed a lot), you can
335 336 337
apply the change to both master 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,
Paul Eggert's avatar
Paul Eggert committed
338 339 340
say in the release branch commit message that there is no need to merge
the commit to master, by starting the commit message with "Backport:".
The gitmerge function excludes these commits from the merge to the master.
341 342 343 344

Some changes should not be merged to master at all, for whatever
reasons.  These should be marked by including something like "Do not
merge to master" or anything that matches gitmerge-skip-regexp (see
Paul Eggert's avatar
Paul Eggert committed
345
admin/gitmerge.el) in the commit message.
346

347 348 349 350 351
** GNU ELPA

This repository does not contain the Emacs Lisp package archive
(elpa.gnu.org).  See admin/notes/elpa for how to access the GNU ELPA
repository.
Juri Linkov's avatar
Juri Linkov committed
352

Paul Eggert's avatar
Paul Eggert committed
353 354 355 356 357 358
** Understanding Emacs internals

The best way to understand Emacs internals is to read the code.  Some
source files, such as xdisp.c, have extensive comments describing the
design and implementation.  The following resources may also help:

359 360
https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
https://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html
Juri Linkov's avatar
Juri Linkov committed
361

Paul Eggert's avatar
Paul Eggert committed
362
or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
Juri Linkov's avatar
Juri Linkov committed
363 364 365

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

366 367
*** Non-ASCII characters in Emacs files

Paul Eggert's avatar
Paul Eggert committed
368 369 370 371 372
If you introduce non-ASCII characters into Emacs source files, use the
UTF-8 encoding unless it cannot do the job for some good reason.
Although it is generally a good idea to add 'coding:' cookies to
non-ASCII source files, cookies are not needed in UTF-8-encoded *.el
files intended for use only with Emacs version 24.5 and later.
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393

*** 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:

Paul Eggert's avatar
Paul Eggert committed
394
- Create a feature branch.
395

Paul Eggert's avatar
Paul Eggert committed
396
- Commit the rename without any changes.
397

Paul Eggert's avatar
Paul Eggert committed
398
- Make other changes.
399

Paul Eggert's avatar
Paul Eggert committed
400 401 402
- Merge the feature branch to the master branch, instead of squashing
  the commits into one.  The commit message on this merge should
  summarize the renames and all the changes.
403

Juri Linkov's avatar
Juri Linkov committed
404 405 406 407


This file is part of GNU Emacs.

408
GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
409
it under the terms of the GNU General Public License as published by
410 411
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
412 413 414 415 416 417 418

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
419
along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
Juri Linkov's avatar
Juri Linkov committed
420 421 422 423

Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
Paul Eggert's avatar
Paul Eggert committed
424
coding: utf-8
Juri Linkov's avatar
Juri Linkov committed
425
end: