mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-22 10:26:20 +00:00
0bf5739b77
c3489d0
* lisp/w32-fns.el (set-message-beep, w32-get-locale-info) (w3...a4d882c
Correct old cell name unbinding when renaming cell.6c12c53
Merge branch 'emacs-25' of git.sv.gnu.org:/srv/git/emacs into...0be6725
Document problem: slow screen refresh on missing font.853b9b9
* admin/admin.el (add-release-logs): Basic check of existing ...5fa80cf
* build-aux/gitlog-to-emacslog: Handle empty generated Change...3c79e51
* admin/admin.el (add-release-logs): Generate ChangeLog if ne...42275df
* doc/misc/texinfo.tex: Revert previous change (Bug#23611).3f4a9d9
* admin/authors.el (authors): First update the ChangeLog.897fb6f
; 'Changes from the pre-25.1 API' copyedits825ca25
Rename vc-stay-local back to vc-cvs-stay-local4efb3e8
* doc/emacs/files.texi (Comparing Files): * doc/emacs/trouble...b995d1e
* doc/misc/eww.texi (Advanced): Fix xref.2e589c0
Fix cross-references between manualsf3d2ded
* doc/misc/vhdl-mode.texi (Sample Init File): Rename node to ...906c810
; * admin/release-process: Move etc/HISTORY from here... ; * ...bea1b65
* admin/admin.el (add-release-logs): Also update etc/HISTORY.503e752
; * CONTRIBUTE: Fix a typo.fbfd478
Avoid aborting due to errors in arguments of 'set-face-attrib...bdfbe6d
; * admin/release-process: Copyedits.44a6aed
; * test/automated/data-tests.el: Standardize license notice.c33ed39
; * test/automated/viper-tests.el: Standardize license notice.df4a14b
Add automated test for viper-tests.elc0139e3
Fix viper undo breakage from undo-boundary changes920d76c
Fix reference to obsolete fn ps-eval-switch18a9bc1
Do not trash symlinks to init file2671179
Don't print the "decomposition" line for control chars in wha...869092c
Bring back xterm pasting with middle mouse5ab0830
Provide workaround for xftfont rendering problemc9f7ec7
* lisp/desktop.el: Disable restore frameset if in non-graphic...30989a0
Mention GTK+ problems in etc/PROBLEMS421e3c4
* lisp/emacs-lisp/package.el (package-refresh-contents):dadfc30
Revert "epg: Add a way to detect gpg1 executable for tests"e41a5cb
Avoid errors with Czech and Slovak input methodsd4ae6d7
epg: Add a way to detect gpg1 executable for testsebc3a94
* lisp/emacs-lisp/package.el: Fix free variable warnings.6e71295
* lisp/emacs-lisp/package.el (package--with-response-buffer):c45d9f6
Improve documentation of 'server-name'3b5e38c
Modernize ASLR advice in etc/PROBLEMS1fe1e0a
* lisp/char-fold.el: Rename from character-fold.el.
355 lines
14 KiB
Plaintext
355 lines
14 KiB
Plaintext
* How developers contribute to GNU Emacs
|
||
|
||
Here is how software developers can contribute to Emacs. (Non-developers: see
|
||
http://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.
|
||
Briefly, the following shell commands build and run Emacs from scratch:
|
||
|
||
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
|
||
./autogen.sh
|
||
./configure
|
||
make
|
||
src/emacs
|
||
|
||
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.
|
||
|
||
** Getting involved with development
|
||
|
||
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.
|
||
|
||
** 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.
|
||
|
||
** 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)".
|
||
|
||
- 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
|
||
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.
|
||
|
||
- 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"'.
|
||
|
||
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/help.el (view-lossage):
|
||
* lisp/kmacro.el (kmacro-edit-lossage):
|
||
* lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
|
||
|
||
(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 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"
|
||
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
|
||
|
||
- 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"'.
|
||
|
||
- If you use Emacs VC, one way to format ChangeLog entries is to 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 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.
|
||
|
||
- 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.
|
||
|
||
** 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, be sure to
|
||
commit it to the release branch; it will be merged to the master
|
||
branch later by the gitmerge function.
|
||
|
||
However, if 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.
|
||
|
||
** Other process information
|
||
|
||
** Emacs Mailing lists.
|
||
|
||
Discussion about Emacs development takes place on emacs-devel@gnu.org.
|
||
|
||
Bug reports and fixes, feature requests and implementations should be
|
||
sent to bug-gnu-emacs@gnu.org, the bug/feature list. This is coupled
|
||
to the http://debbugs.gnu.org tracker.
|
||
|
||
The Savannah info page http://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. 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 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.
|
||
|
||
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.
|
||
|
||
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
|
||
the entry with "+++". Otherwise do not mark it.
|
||
|
||
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.
|
||
|
||
** 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
|
||
http://www.gnu.org/software/emacs/manual/html_node/ert/
|
||
or run 'info "(ert)"' for 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.
|
||
|
||
** 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
|
||
|
||
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 <http://www.gnu.org/licenses/>.
|
||
|
||
Local variables:
|
||
mode: outline
|
||
paragraph-separate: "[ ]*$"
|
||
coding: utf-8
|
||
end:
|