CONTRIBUTE 15.4 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
http://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 10
Emacs development uses Git on Savannah for its main repository.
Briefly, the following shell commands build and run Emacs from scratch:
Juri Linkov's avatar
Juri Linkov committed
11

Paul Eggert's avatar
Paul Eggert committed
12 13 14 15 16
	git config --global user.name 'Your Name'
	git config --global user.email 'your.name@example.com'
	git config --global transfer.fsckObjects true
	git clone git://git.sv.gnu.org/emacs.git
	cd emacs
17
	./autogen.sh all
Paul Eggert's avatar
Paul Eggert committed
18 19 20
	./configure
	make
	src/emacs
Juri Linkov's avatar
Juri Linkov committed
21

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

Paul Eggert's avatar
Paul Eggert committed
27
** Getting involved with development
Juri Linkov's avatar
Juri Linkov committed
28

Paul Eggert's avatar
Paul Eggert committed
29 30 31 32 33 34 35 36
You can subscribe to the emacs-devel@gnu.org mailing list, paying
attention to postings with subject lines containing "emacs-announce",
as these discuss important events like feature freezes.  See
http://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list
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
37

Paul Eggert's avatar
Paul Eggert committed
38
** Committing changes by others
Juri Linkov's avatar
Juri Linkov committed
39

Paul Eggert's avatar
Paul Eggert committed
40 41 42
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.
Juri Linkov's avatar
Juri Linkov committed
43

44
** Commit messages
45

Paul Eggert's avatar
Paul Eggert committed
46 47 48
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):
49 50 51 52

	Deactivate shifted region

	Do not silently extend a region that is not highlighted;
53
	this can happen after a shift (Bug#19003).
54 55 56 57 58
	* 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
59 60 61
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:
62

Eli Zaretskii's avatar
Eli Zaretskii committed
63 64
- 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
65
  semicolon and a space "; ", the commit message will be ignored when
Eli Zaretskii's avatar
Eli Zaretskii committed
66 67 68 69 70
  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.
71

72
- Limit lines in commit messages to 78 characters, unless they consist
73 74 75 76 77
  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.
78 79 80 81 82

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

83
- If the commit has more than one author, the commit message should
84
  contain separate lines to mention the other authors, like the
85
  following:
Eli Zaretskii's avatar
Eli Zaretskii committed
86 87 88 89 90 91 92 93 94 95 96

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

98 99
- Commit messages should contain only printable UTF-8 characters.

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

103
- Any lines of the commit message that start with "; " are omitted
104 105
  from the generated ChangeLog.

Eli Zaretskii's avatar
Eli Zaretskii committed
106 107 108 109 110
- 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
111 112 113 114 115 116
- Emacs generally follows the GNU coding standards for ChangeLogs: see
  http://www.gnu.org/prep/standards/html_node/Change-Logs.html
  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.
117

Paul Eggert's avatar
Paul Eggert committed
118 119 120 121 122 123
- 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
  http://www.gnu.org/prep/standards/html_node/Comments.html
  or run 'info "(standards)Comments"'.
124

125 126 127
  They are preserved indefinitely, and have a reasonable chance of
  being read in the future, so it's better that they have good
  presentation.
128 129 130 131

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

132 133
- Preferred form for several entries with the same content:

134 135 136 137 138 139
	* 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)
140 141 142

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

Eli Zaretskii's avatar
Eli Zaretskii committed
143 144 145 146
- 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.
147 148 149 150

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

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

159 160
** Generating ChangeLog entries

Paul Eggert's avatar
Paul Eggert committed
161 162 163
- You can use Emacs functions to write ChangeLog entries; see
  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
  or run 'info "(emacs)Change Log Commands"'.
164 165

- If you use Emacs VC, one way to format ChangeLog entries is to create
166
  a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
167
  usual.  Do not register the ChangeLog file under git; instead, use
168
  'C-c C-a' to insert its contents into your *vc-log* buffer.
169
  Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
170
  does by default), they will be filled in for you automatically.
171 172 173 174 175 176 177 178

- 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
179
** Branches
180

Paul Eggert's avatar
Paul Eggert committed
181 182 183 184 185 186 187 188
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
189
admin/notes/git-workflow.
190 191 192

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
Paul Eggert's avatar
Paul Eggert committed
193
branch later by the gitmerge function.
194

Eli Zaretskii's avatar
Eli Zaretskii committed
195 196
Documentation fixes (in doc strings, in manuals, and in comments)
should always go to the release branch, if the documentation to be
197 198 199
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
200

201
When you know that the change will be difficult to merge to the
Paul Eggert's avatar
Paul Eggert committed
202
master (e.g., because the code on master has changed a lot), you can
203 204 205
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
206 207 208
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.
209 210 211 212

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
213
admin/gitmerge.el) in the commit message.
214

215 216 217 218 219
** 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
220 221 222 223 224

** Emacs Mailing lists.

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

225 226
Bug reports and fixes, feature requests and implementations should be
sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
Paul Eggert's avatar
Paul Eggert committed
227
to the http://debbugs.gnu.org tracker.
Juri Linkov's avatar
Juri Linkov committed
228

Paul Eggert's avatar
Paul Eggert committed
229 230 231
The Savannah info page http://savannah.gnu.org/mail/?group=emacs
describes how to subscribe to the mailing lists, or see the list
archives.
Juri Linkov's avatar
Juri Linkov committed
232

233 234
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
235 236 237
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'.
238

239 240
** Issue tracker (a.k.a. "bug tracker")

Paul Eggert's avatar
Paul Eggert committed
241 242 243 244
The Emacs issue tracker at http://debbugs.gnu.org lets you 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.
245 246 247 248

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

249 250 251 252 253 254 255 256 257
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
258
admin/notes/bug-triage.
259

Paul Eggert's avatar
Paul Eggert committed
260
** Documenting your changes
Juri Linkov's avatar
Juri Linkov committed
261

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

264 265 266 267 268
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
269
the entry with "+++".  Otherwise do not mark it.
Juri Linkov's avatar
Juri Linkov committed
270

271 272 273 274 275 276 277
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
@findex for functions/commands.  For the full list of predefine indices, see
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
or run the shell command 'info "(texinfo)Predefined Indices"'.

Paul Eggert's avatar
Paul Eggert committed
278 279 280
For more specific tips on Emacs's doc style, see
http://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
Use 'checkdoc' to check for documentation errors before submitting a patch.
281

Paul Eggert's avatar
Paul Eggert committed
282
** Testing your changes
283 284

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

Paul Eggert's avatar
Paul Eggert committed
289 290 291 292
Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See
http://www.gnu.org/software/emacs/manual/html_node/ert/
or run 'info "(ert)"' for for more information on writing and running
tests.
293

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

297
To run tests on the entire Emacs tree, run "make check" from the
298 299 300
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.
301

Paul Eggert's avatar
Paul Eggert committed
302 303 304 305 306 307 308 309
** 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:

http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
http://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html
Juri Linkov's avatar
Juri Linkov committed
310

Paul Eggert's avatar
Paul Eggert committed
311
or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
Juri Linkov's avatar
Juri Linkov committed
312 313 314

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

315 316
*** Non-ASCII characters in Emacs files

Paul Eggert's avatar
Paul Eggert committed
317 318 319 320 321
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.
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342

*** 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
343
- Create a feature branch.
344

Paul Eggert's avatar
Paul Eggert committed
345
- Commit the rename without any changes.
346

Paul Eggert's avatar
Paul Eggert committed
347
- Make other changes.
348

Paul Eggert's avatar
Paul Eggert committed
349 350 351
- 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.
352

Juri Linkov's avatar
Juri Linkov committed
353 354 355 356


This file is part of GNU Emacs.

357
GNU Emacs is free software: you can redistribute it and/or modify
Juri Linkov's avatar
Juri Linkov committed
358
it under the terms of the GNU General Public License as published by
359 360
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
Juri Linkov's avatar
Juri Linkov committed
361 362 363 364 365 366 367

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
368
along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Juri Linkov's avatar
Juri Linkov committed
369 370 371 372

Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
Paul Eggert's avatar
Paul Eggert committed
373
coding: utf-8
Juri Linkov's avatar
Juri Linkov committed
374
end: