* Information for Emacs Developers.
An "Emacs Developer" is someone who contributes a lot of code or
-documentation to the Emacs repository. Generally, they have write
+documentation to the Emacs repository. Generally, they have write
access to the Emacs git repository on Savannah
https://savannah.gnu.org/git/?group=emacs.
** Write access to the Emacs repository.
Once you become a frequent contributor to Emacs, we can consider
-giving you write access to the version-control repository. Request
-access on the emacs-devel@gnu.org mailing list.
+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.
** Using the Emacs repository
-Emacs uses git for the source code repository.
+Emacs uses Git for the source code repository.
See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
Alternately, see admin/notes/git-workflow.
If committing changes written by someone else, make the commit in
-their name, not yours. git distinguishes between the author
+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.
** Commit messages
-When a release is prepared, the commit messages are used to generate
-the ChangeLog file. So a typical patch does not touch any of the
-ChangeLog files in the repository, but contains the ChangeLog entries
-in its message. Here is an example commit message (indented):
+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):
Deactivate shifted region
Do not silently extend a region that is not highlighted;
- this can happen after a shift.
+ this can happen after a shift (Bug#19003).
* 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.
- Fixes: bug#19003
-The general format is as follows.
+Below are some rules and recommendations for formatting commit
+messages:
-- Start with a single unindented summary line explaining the change,
- then an empty line, then unindented ChangeLog entries.
+- 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.
- Limit lines in commit messages to 78 characters, unless they consist
of a single word of at most 140 characters; this is enforced by a
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.
+- If the commit has more than one author, the commit message should
+ contain separate lines to mention the other authors, like the
+ following:
+
+ 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)".
- Commit messages should contain only printable UTF-8 characters.
- Commit messages should not contain the "Signed-off-by:" lines that
are used in some other projects.
+- Any lines of the commit message that start with "; " are omitted
+ from the generated ChangeLog.
+
+- 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.
+
- Emacs generally follows the GNU coding standards when it comes to
ChangeLogs:
- http://www.gnu.org/prep/standards/html_node/Change-Logs.html . 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.
+ 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.
- Some of the rules in the GNU coding standards section 5.2
"Commenting Your Work" also apply to ChangeLog entries: they must be
(Rather than anything involving "ditto" and suchlike.)
-- If the commit has authors other than yourself, the commit message
- should contain a separate line like the following:
-
- 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
-
-- If the commit fixes a bug, append a separate line
-
- Fixes: bug#NNNN
-
- where NNNN is the bug number.
-
-- In ChangeLog entries, there is no standard or recommended way to
- identify revisions.
+- 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.
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!esr@thyrsus.com". Often, "my previous commit"
+ "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
will suffice.
-- There is no need to mention files such as NEWS, MAINTAINERS, and
- FOR-RELEASE, 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.
-
-- If a commit message's first line starts with "; ", the message is
- ignored when generating ChangeLog history files via 'make ChangeLog'
- or via 'make change-history'. You can use "; " for minor commits
- that do not need separate ChangeLog entries, as well as commits that
- only modify files that don't need these entries at all.
+- 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.
** Generating ChangeLog entries
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 into your *vc-log* buffer.
- Or if `log-edit-hook' includes `log-edit-insert-changelog' (which it
+ Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it
does by default), they will be filled in for you automatically.
- Alternatively, you can use the vc-dwim command to maintain commit
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.
-** branches
+** Branches
Development normally takes places on the trunk.
Sometimes specialized features are developed on separate branches
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. Announcements about the freeze
-(and other important events) are made on the info-gnu-emacs mailing
-list, and not anywhere else.
-
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
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.
+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.
** Other process information
-See all the files in admin/notes/* . In particular, see
-admin/notes/newfile, see admin/notes/repo.
-
-*** 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.
-
** Emacs Mailing lists.
Discussion about Emacs development takes place on emacs-devel@gnu.org.
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
-packages the patch's commit message and changes.
+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'.
+
+** 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.
+
+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.
** Document your changes.
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
-the entry with "+++". Otherwise do not mark it.
+the entry with "+++". Otherwise do not mark it.
Please see (info "(elisp)Documentation Tips") or
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
-for more specific tips on Emacs's doc style. Use `checkdoc' to check
+for more specific tips on Emacs's doc style. Use 'checkdoc' to check
for documentation errors before submitting a patch.
** Test your changes.
Please test your changes before committing them or sending them to the
-list.
+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 (info
"(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
for more information on writing and running 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/automated". From the "test/automated" directory, run "make
+"test/". From the "test/" directory, run "make
<filename>" to run the tests for <filename>.el(c). See
-"test/automated/Makefile" for more information.
+"test/Makefile" for more information.
+
+Tests which are tagged ":expensive-test" are enabled additionally, if
+you run "make check-expensive" from the top-level directory. "make
+<filename>" as mentioned above incorporates expensive tests for
+<filename>.el(c). You can also define any ert selector on the command
+line. So "make check SELECTOR=nil" is equivalent to "make
+check-expensive".
+
+You could also use predefined selectors of the Makefile. "make
+<filename> SELECTOR='$(SELECTOR_DEFAULT)'" runs all tests for
+<filename>.el(c) except the tests tagged as expensive.
+
+Selectors can be defined with different methods, see (info "(ert)Test
+Selectors") or
+https://www.gnu.org/software/emacs/manual/html_node/ert/Test-Selectors.html
+If your test file contains the tests "test-foo", "test2-foo" and
+"test-foo-remote", and you want to run only the former two tests, you
+could use a regexp: "make <filename> SELECTOR='\"foo$$\"'" .
** 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.
+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.
The file etc/DEBUG describes how to debug Emacs bugs.
+*** 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.
+
\f
This file is part of GNU Emacs.