1 * How developers contribute to GNU Emacs
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
5 or run the shell command 'info "(emacs)Contributing"'.)
7 ** The Emacs repository
9 Emacs development uses Git on Savannah for its main repository.
10 To configure Git for Emacs development, you can run the following:
12 git config --global user.name 'Your Name'
13 git config --global user.email 'your.name@example.com'
14 git config --global transfer.fsckObjects true
16 The following shell commands then build and run Emacs from scratch:
18 git clone git://git.sv.gnu.org/emacs.git
26 http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
27 http://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
28 admin/notes/git-workflow.
30 ** Getting involved with development
32 Discussion about Emacs development takes place on emacs-devel@gnu.org.
33 You can subscribe to the emacs-devel@gnu.org mailing list.
34 If you want to get only the important mails (for things like
35 feature freezes), choose to receive only the 'emacs-announce' topic
36 (although so far this feature has not been well or consistently used).
37 See https://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list
38 instructions and archives. You can develop and commit changes in your
39 own copy of the repository, and discuss proposed changes on the
40 mailing list. Frequent contributors to Emacs can request write access
43 Bug reports and fixes, feature requests and patches/implementations
44 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 the command 'M-x report-emacs-bug RET' to report issues to the tracker
47 (described below). Be prepared to receive comments and requests for
48 changes in your patches, following your submission.
50 The Savannah info page https://savannah.gnu.org/mail/?group=emacs
51 describes how to subscribe to the mailing lists, or see the list
54 To email a patch you can use a shell command like 'git format-patch -1'
55 to create a file, and then attach the file to your email. This nicely
56 packages the patch's commit message and changes. To send just one
57 such patch without additional remarks, you can use a command like
58 'git send-email --to=bug-gnu-emacs@gnu.org 0001-DESCRIPTION.patch'.
60 Once the cumulative amount of your submissions exceeds about 15 lines
61 of non-trivial changes, we will need you to assign to the FSF the
62 copyright for your contributions. Ask on emacs-devel@gnu.org, and we
63 will send you the necessary form together with the instructions to
64 fill and email it, in order to start this legal paperwork.
66 ** Issue tracker (a.k.a. "bug tracker")
68 The Emacs issue tracker at https://debbugs.gnu.org lets you view bug
69 reports and search the database for bugs matching several criteria.
70 Messages posted to the bug-gnu-emacs@gnu.org mailing list, mentioned
71 above, are recorded by the tracker with the corresponding
72 bugs/issues. If a message to the bug tracker contains a patch, please
73 include the string "[PATCH]" in the subject of the message in order to
74 let the bug tracker tag the bug properly.
76 GNU ELPA has a 'debbugs' package that allows accessing the tracker
79 Bugs needs regular attention. A large backlog of bugs is
80 disheartening to the developers, and a culture of ignoring bugs is
81 harmful to users, who expect software that works. Bugs have to be
82 regularly looked at and acted upon. Not all bugs are critical, but at
83 the least, each bug needs to be regularly re-reviewed to make sure it
84 is still reproducible.
86 The process of going through old or new bugs and acting on them is
87 called bug triage. This process is described in the file
88 admin/notes/bug-triage.
90 ** Documenting your changes
92 Any change that matters to end-users should have an entry in etc/NEWS.
93 Try to start each NEWS entry with a sentence that summarizes the entry
94 and takes just one line -- this will allow to read NEWS in Outline
95 mode after hiding the body of each entry.
97 Doc-strings should be updated together with the code.
99 New defcustom's should always have a ':version' tag stating the first
100 Emacs version in which they will appear. Likewise with defcustom's
101 whose value is changed -- update their ':version' tag.
103 Think about whether your change requires updating the manuals. If you
104 know it does not, mark the NEWS entry with "---". If you know
105 that *all* the necessary documentation updates have been made as part
106 of your changes or those by others, mark the entry with "+++".
107 Otherwise do not mark it.
109 If your change requires updating the manuals to document new
110 functions/commands/variables/faces, then use the proper Texinfo
111 command to index them; for instance, use @vindex for variables and
112 @findex for functions/commands. For the full list of predefined indices, see
113 https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
114 or run the shell command 'info "(texinfo)Predefined Indices"'.
116 We prefer American English both in doc strings and in the manuals.
117 That includes both spelling (e.g., "behavior", not "behaviour") and
118 the convention of leaving 2 spaces between sentences.
120 For more specific tips on Emacs's doc style, see
121 https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
122 Use 'checkdoc' to check for documentation errors before submitting a patch.
124 ** Testing your changes
126 Please test your changes before committing them or sending them to the
127 list. If possible, add a new test along with any bug fix or new
128 functionality you commit (of course, some changes cannot be easily
131 Emacs uses ERT, Emacs Lisp Regression Testing, for testing. See
132 https://www.gnu.org/software/emacs/manual/html_node/ert/
133 or run 'info "(ert)"' for more information on writing and running
136 If your test lasts longer than some few seconds, mark it in its
137 'ert-deftest' definition with ":tags '(:expensive-test)".
139 To run tests on the entire Emacs tree, run "make check" from the
140 top-level directory. Most tests are in the directory "test/". From
141 the "test/" directory, run "make <filename>" to run the tests for
142 <filename>.el(c). See "test/README" for more information.
146 Ordinarily, a change you commit should contain a log entry in its
147 commit message and should not touch the repository's ChangeLog files.
148 Here is an example commit message (indented):
150 Deactivate shifted region
152 Do not silently extend a region that is not highlighted;
153 this can happen after a shift (Bug#19003).
154 * doc/emacs/mark.texi (Shift Selection): Document the change.
155 * lisp/window.el (handle-select-window):
156 * src/frame.c (Fhandle_switch_frame, Fselected_frame):
159 Occasionally, commit messages are collected and prepended to a
160 ChangeLog file, where they can be corrected. It saves time to get
161 them right the first time, so here are guidelines for formatting them:
163 - Start with a single unindented summary line explaining the change;
164 do not end this line with a period. If that line starts with a
165 semicolon and a space "; ", the commit message will be ignored when
166 generating the ChangeLog file. Use this for minor commits that do
167 not need separate ChangeLog entries, such as changes in etc/NEWS.
169 - After the summary line, there should be an empty line, then
170 unindented ChangeLog entries.
172 - Limit lines in commit messages to 78 characters, unless they consist
173 of a single word of at most 140 characters; this is enforced by a
174 commit hook. It's nicer to limit the summary line to 50 characters;
175 this isn't enforced. If the change can't be summarized so briefly,
176 add a paragraph after the empty line and before the individual file
179 - If only a single file is changed, the summary line can be the normal
180 file first line (starting with the asterisk). Then there is no
181 individual files section.
183 - If the commit has more than one author, the commit message should
184 contain separate lines to mention the other authors, like the
187 Co-authored-by: Joe Schmoe <j.schmoe@example.org>
189 - If the commit is a tiny change that is exempt from copyright paperwork,
190 the commit message should contain a separate line like the following:
192 Copyright-paperwork-exempt: yes
194 - The commit message should contain "Bug#NNNNN" if it is related to
195 bug number NNNNN in the debbugs database. This string is often
196 parenthesized, as in "(Bug#19003)".
198 - When citing URLs, prefer https: to http: when either will do. In
199 particular, gnu.org and fsf.org URLs should start with "https:".
201 - Commit messages should contain only printable UTF-8 characters.
203 - Commit messages should not contain the "Signed-off-by:" lines that
204 are used in some other projects.
206 - Any lines of the commit message that start with "; " are omitted
207 from the generated ChangeLog.
209 - Explaining the rationale for a design choice is best done in comments
210 in the source code. However, sometimes it is useful to describe just
211 the rationale for a change; that can be done in the commit message
212 between the summary line and the file entries.
214 - Emacs generally follows the GNU coding standards for ChangeLogs: see
215 https://www.gnu.org/prep/standards/html_node/Change-Logs.html
216 or run 'info "(standards)Change Logs"'. One exception is that
217 commits still sometimes quote `like-this' (as the standards used to
218 recommend) rather than 'like-this' or ‘like this’ (as they do now),
219 as `...' is so widely used elsewhere in Emacs.
221 - Some commenting rules in the GNU coding standards also apply
222 to ChangeLog entries: they must be in English, and be complete
223 sentences starting with a capital and ending with a period (except
224 the summary line should not end in a period). See
225 https://www.gnu.org/prep/standards/html_node/Comments.html
226 or run 'info "(standards)Comments"'. American English is preferred
227 in Emacs; that includes spelling and leaving 2 blanks between
230 They are preserved indefinitely, and have a reasonable chance of
231 being read in the future, so it's better that they have good
234 - Use the present tense; describe "what the change does", not "what
237 - Preferred form for several entries with the same content:
239 * lisp/menu-bar.el (clipboard-yank, clipboard-kill-ring-save)
240 (clipboard-kill-region):
241 * lisp/eshell/esh-io.el (eshell-virtual-targets)
242 (eshell-clipboard-append):
243 Replace option gui-select-enable-clipboard with
244 select-enable-clipboard; renamed October 2014. (Bug#25145)
246 (Rather than anything involving "ditto" and suchlike.)
248 - There is no standard or recommended way to identify revisions in
249 ChangeLog entries. Using Git SHA1 values limits the usability of
250 the references to Git, and will become much less useful if Emacs
251 switches to a different VCS. So we recommend against that.
253 One way to identify revisions is by quoting their summary line.
254 Another is with an action stamp - an RFC3339 date followed by !
255 followed by the committer's email - for example,
256 "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
259 - There is no need to mention files such as NEWS and MAINTAINERS, or
260 to indicate regeneration of files such as 'lib/gnulib.mk', in the
261 ChangeLog entry. "There is no need" means you don't have to, but
262 you can if you want to.
264 ** Generating ChangeLog entries
266 - You can use Emacs functions to write ChangeLog entries; see
267 https://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
268 or run 'info "(emacs)Change Log Commands"'.
270 - If you use Emacs VC, one way to format ChangeLog entries is to create
271 a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
272 usual. Do not register the ChangeLog file under git; instead, use
273 'C-c C-a' to insert its contents into your *vc-log* buffer.
274 Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
275 does by default), they will be filled in for you automatically.
277 - Alternatively, you can use the vc-dwim command to maintain commit
278 messages. When you create a source directory, run the shell command
279 'git-changelog-symlink-init' to create a symbolic link from
280 ChangeLog to .git/c/ChangeLog. Edit this ChangeLog via its symlink
281 with Emacs commands like 'C-x 4 a', and commit the change using the
282 shell command 'vc-dwim --commit'. Type 'vc-dwim --help' for more.
284 ** Committing changes by others
286 If committing changes written by someone else, commit in their name,
287 not yours. You can use 'git commit --author="AUTHOR"' to specify a
292 Future development normally takes place on the master branch.
293 Sometimes specialized features are developed on other branches before
294 possibly being merged to the master. Release branches are named
295 "emacs-NN" where NN is the major version number, and are mainly
296 intended for more-conservative changes such as bug fixes. Typically,
297 collective development is active on the master branch and possibly on
298 the current release branch. Periodically, the current release branch
299 is merged into the master, using the gitmerge function described in
300 admin/notes/git-workflow.
302 If you are fixing a bug that exists in the current release, you should
303 generally commit it to the release branch; it will be merged to the
304 master branch later by the gitmerge function. However, when the
305 release branch is for Emacs version NN.2 and later, or when it is for
306 Emacs version NN.1 that is in the very last stages of its pretest,
307 that branch is considered to be in a feature freeze: only bug fixes
308 that are "safe" or are fixing major problems should go to the release
309 branch, the rest should be committed to the master branch. This is so
310 to avoid destabilizing the next Emacs release. If you are unsure
311 whether your bug fix is "safe" enough for the release branch, ask on
312 the emacs-devel mailing list.
314 Documentation fixes (in doc strings, in manuals, in NEWS, and in
315 comments) should always go to the release branch, if the documentation
316 to be fixed exists and is relevant to the release-branch codebase.
317 Doc fixes are always considered "safe" -- even when a release branch
318 is in feature freeze, it can still receive doc fixes.
320 When you know that the change will be difficult to merge to the
321 master (e.g., because the code on master has changed a lot), you can
322 apply the change to both master and branch yourself. It could also
323 happen that a change is cherry-picked from master to the release
324 branch, and so doesn't need to be merged back. In these cases,
325 say in the release branch commit message that there is no need to merge
326 the commit to master, by starting the commit message with "Backport:".
327 The gitmerge function excludes these commits from the merge to the master.
329 Some changes should not be merged to master at all, for whatever
330 reasons. These should be marked by including something like "Do not
331 merge to master" or anything that matches gitmerge-skip-regexp (see
332 admin/gitmerge.el) in the commit message.
336 This repository does not contain the Emacs Lisp package archive
337 (elpa.gnu.org). See admin/notes/elpa for how to access the GNU ELPA
340 ** Understanding Emacs internals
342 The best way to understand Emacs internals is to read the code. Some
343 source files, such as xdisp.c, have extensive comments describing the
344 design and implementation. The following resources may also help:
346 https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
347 https://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html
349 or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
351 The file etc/DEBUG describes how to debug Emacs bugs.
353 *** Non-ASCII characters in Emacs files
355 If you introduce non-ASCII characters into Emacs source files, use the
356 UTF-8 encoding unless it cannot do the job for some good reason.
357 Although it is generally a good idea to add 'coding:' cookies to
358 non-ASCII source files, cookies are not needed in UTF-8-encoded *.el
359 files intended for use only with Emacs version 24.5 and later.
361 *** Useful files in the admin/ directory
363 See all the files in admin/notes/* . In particular, see
364 admin/notes/newfile, see admin/notes/repo.
366 The file admin/MAINTAINERS records the areas of interest of frequent
367 Emacs contributors. If you are making changes in one of the files
368 mentioned there, it is a good idea to consult the person who expressed
369 an interest in that file, and/or get his/her feedback for the changes.
370 If you are a frequent contributor and have interest in maintaining
371 specific files, please record those interests in that file, so that
372 others could be aware of that.
376 Git does not explicitly represent a file renaming; it uses a percent
377 changed heuristic to deduce that a file was renamed. So if you are
378 planning to make extensive changes to a file after renaming it (or
379 moving it to another directory), you should:
381 - Create a feature branch.
383 - Commit the rename without any changes.
385 - Make other changes.
387 - Merge the feature branch to the master branch, instead of squashing
388 the commits into one. The commit message on this merge should
389 summarize the renames and all the changes.
393 This file is part of GNU Emacs.
395 GNU Emacs is free software: you can redistribute it and/or modify
396 it under the terms of the GNU General Public License as published by
397 the Free Software Foundation, either version 3 of the License, or
398 (at your option) any later version.
400 GNU Emacs is distributed in the hope that it will be useful,
401 but WITHOUT ANY WARRANTY; without even the implied warranty of
402 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
403 GNU General Public License for more details.
405 You should have received a copy of the GNU General Public License
406 along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
410 paragraph-separate: "[
\f]*$"