mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-05 08:53:45 +00:00
2416790595
* CONTRIBUTE: Ask contributors to test out-of-tree builds when making build system changes.
440 lines
19 KiB
Plaintext
440 lines
19 KiB
Plaintext
* How developers contribute to GNU Emacs
|
||
|
||
Here is how software developers can contribute to Emacs. (Non-developers: see
|
||
https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
|
||
or run the shell command 'info "(emacs)Contributing"'.)
|
||
|
||
** The Emacs repository
|
||
|
||
Emacs development uses Git on Savannah for its main repository.
|
||
To configure Git for Emacs development, you can run the following:
|
||
|
||
git config --global user.name 'Your Name'
|
||
git config --global user.email 'your.name@example.com'
|
||
git config --global transfer.fsckObjects true
|
||
|
||
The following shell commands then build and run Emacs from scratch:
|
||
|
||
git clone git://git.sv.gnu.org/emacs.git
|
||
cd emacs
|
||
./autogen.sh
|
||
./configure
|
||
make
|
||
src/emacs
|
||
|
||
For more details, see
|
||
https://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
|
||
https://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
|
||
admin/notes/git-workflow.
|
||
|
||
** Getting involved with development
|
||
|
||
Discussion about Emacs development takes place on emacs-devel@gnu.org.
|
||
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
|
||
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.
|
||
|
||
Bug reports and fixes, feature requests and patches/implementations
|
||
should be sent to bug-gnu-emacs@gnu.org, the bug/feature list. This
|
||
is coupled to the https://debbugs.gnu.org tracker. It is best to use
|
||
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.
|
||
|
||
The Savannah info page https://savannah.gnu.org/mail/?group=emacs
|
||
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
|
||
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 sending patches whose author is someone
|
||
other than the email sender.
|
||
|
||
Once the cumulative amount of your submissions exceeds a dozen or so
|
||
lines of non-trivial changes, we will need you to assign to the FSF
|
||
the copyright for your contributions. (To see how many lines were
|
||
non-trivially changed, count only added and modified lines in the
|
||
patched code. Consider an added or changed line non-trivial if it
|
||
includes at least one identifier, string, or substantial comment.)
|
||
In most cases, to start the assignment process you should download
|
||
https://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/Copyright/request-assign.future
|
||
and return the completed information to the address at the top.
|
||
(There are other assignment options, but they are much less commonly used.)
|
||
If you have questions about the assignment process, you can ask the
|
||
address listed on the form, and/or emacs-devel@gnu.org.
|
||
|
||
** Issue tracker (a.k.a. "bug tracker")
|
||
|
||
The Emacs issue tracker at https://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. 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.
|
||
|
||
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.
|
||
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.
|
||
|
||
Doc-strings should be updated together with the code.
|
||
|
||
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.
|
||
|
||
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 as part
|
||
of your changes or those by others, mark the entry with "+++".
|
||
Otherwise do not mark it.
|
||
|
||
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 predefined indices, see
|
||
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
|
||
or run the shell command 'info "(texinfo)Predefined Indices"'.
|
||
|
||
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.
|
||
|
||
For more specific tips on Emacs's doc style, see
|
||
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
|
||
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
|
||
https://www.gnu.org/software/emacs/manual/html_node/ert/
|
||
or run 'info "(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/". From
|
||
the "test/" directory, run "make <filename>" to run the tests for
|
||
<filename>.el(c). See "test/README" for more information.
|
||
|
||
If you're making changes that involve the Emacs build system, please
|
||
test 'out-of-tree' builds as well, i.e.:
|
||
|
||
mkdir emacs-build
|
||
cd emacs-build
|
||
../path-to-emacs-sources/configure
|
||
make
|
||
|
||
** Commit messages
|
||
|
||
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):
|
||
|
||
Deactivate shifted region
|
||
|
||
Do not silently extend a region that is not highlighted;
|
||
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.
|
||
|
||
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:
|
||
|
||
- Start with a single unindented summary line explaining the change;
|
||
do not end this line with a period. If that line starts with a
|
||
semicolon and a space "; ", the commit 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
|
||
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.
|
||
|
||
- 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.
|
||
|
||
- 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)".
|
||
|
||
- When citing URLs, prefer https: to http: when either will do. In
|
||
particular, gnu.org and fsf.org URLs should start with "https:".
|
||
|
||
- 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 for ChangeLogs: see
|
||
https://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.
|
||
|
||
- 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
|
||
https://www.gnu.org/prep/standards/html_node/Comments.html
|
||
or run 'info "(standards)Comments"'. American English is preferred
|
||
in Emacs; that includes spelling and leaving 2 blanks between
|
||
sentences.
|
||
|
||
They are preserved indefinitely, and have a reasonable chance of
|
||
being read in the future, so it's better that they have good
|
||
presentation.
|
||
|
||
- Use the present tense; describe "what the change does", not "what
|
||
the change did".
|
||
|
||
- Preferred form for several entries with the same content:
|
||
|
||
* 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)
|
||
|
||
(Rather than anything involving "ditto" and suchlike.)
|
||
|
||
- 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 doing only that.
|
||
|
||
One way to identify revisions is by quoting their summary line.
|
||
Prefixing the summary with the commit date can give useful context
|
||
(use 'git show -s "--pretty=format:%cd \"%s\"" --date=short HASH' to
|
||
produce that). Often, "my previous commit" will suffice.
|
||
|
||
- There is no need to mention files such as NEWS and MAINTAINERS, or
|
||
to indicate regeneration of files such as 'lib/gnulib.mk', in the
|
||
ChangeLog entry. "There is no need" means you don't have to, but
|
||
you can if you want to.
|
||
|
||
** Generating ChangeLog entries
|
||
|
||
- 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
|
||
https://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
|
||
or run 'info "(emacs)Change Log Commands"'.
|
||
|
||
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.
|
||
|
||
- Instead of Emacs VC, 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.
|
||
|
||
** 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.
|
||
|
||
** Branches
|
||
|
||
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
|
||
admin/notes/git-workflow.
|
||
|
||
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.
|
||
|
||
When you know that the change will be difficult to merge to the
|
||
master (e.g., because the code on master has changed a lot), you can
|
||
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,
|
||
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.
|
||
|
||
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
|
||
admin/gitmerge.el) in the commit message.
|
||
|
||
** 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.
|
||
|
||
** 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:
|
||
|
||
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
|
||
|
||
or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
|
||
|
||
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, 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.
|
||
|
||
*** 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 the master branch, instead of squashing
|
||
the commits into one. The commit message on this merge should
|
||
summarize the renames and all the changes.
|
||
|
||
|
||
|
||
This file is part of GNU Emacs.
|
||
|
||
GNU Emacs is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
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
|
||
along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
|
||
|
||
Local variables:
|
||
mode: outline
|
||
paragraph-separate: "[ ]*$"
|
||
coding: utf-8
|
||
end:
|