Commit 39372e1a authored by Ken Raeburn's avatar Ken Raeburn
Browse files

merge from trunk

parents 6a312190 e11aaee2

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.
......@@ -3,13 +3,11 @@
(fill-column . 70)))
(c-mode . ((c-file-style . "GNU")))
(objc-mode . ((c-file-style . "GNU")))
;; You must set bugtracker_debbugs_url in your bazaar.conf for this to work.
;; See admin/notes/bugtracker.
(log-edit-mode . ((log-edit-rewrite-fixes
"[ \n](bug#\\([0-9]+\\))" . "debbugs:\\1")
(log-edit-font-lock-gnu-style . t)))
(log-edit-mode . ((log-edit-font-lock-gnu-style . t)
(log-edit-setup-add-author . t)))
(change-log-mode . ((add-log-time-zone-rule . t)
(fill-column . 74)
(bug-reference-url-format . "http://debbugs.gnu.org/%s")
(mode . bug-reference)))
(diff-mode . ((mode . whitespace))))
(diff-mode . ((mode . whitespace)))
(emacs-lisp-mode . ((indent-tabs-mode . nil))))
# Attributes of Emacs files in the Git repository.
# Copyright 2015 Free Software Foundation, Inc.
# 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/>.
# A few files use CRLF endings, even on non-Microsoft platforms.
# Do not warn about trailing whitespace with these files.
*.bat whitespace=cr-at-eol
admin/charsets/mapfiles/PTCP154 whitespace=cr-at-eol
leim/MISC-DIC/cangjie-table.b5 whitespace=cr-at-eol
leim/MISC-DIC/cangjie-table.cns whitespace=cr-at-eol
leim/MISC-DIC/pinyin.map whitespace=cr-at-eol
lib-src/update-game-score.exe.manifest whitespace=cr-at-eol
nt/nmake.defs whitespace=cr-at-eol
test/etags/c-src/dostorture.c whitespace=cr-at-eol
test/etags/cp-src/c.C whitespace=cr-at-eol
test/etags/html-src/algrthms.html whitespace=cr-at-eol
# The upstream maintainer does not want to remove trailing whitespace.
doc/misc/texinfo.tex -whitespace=blank-at-eol
# Some files should not be treated as text when diffing or merging.
*.gpg binary
*.gz binary
*.icns binary
*.ico binary
*.pbm binary
*.pdf binary
*.png binary
*.sig binary
*.tiff binary
etc/e/eterm-color binary
# Hooks for non-default diff hunk headers; see autogen.sh.
*.el diff=elisp
*.texi diff=texinfo
configure
aclocal.m4
compile
config.guess
config.sub
depcomp
install-sh
missing
# Files that Git should ignore in the Emacs source directory.
# Copyright 2009-2015 Free Software Foundation, Inc.
# 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/>.
# Currently we assume only Git 1.7.1 (April 2010) or later, so this
# file does not rely on "**" in patterns. The "**" feature was added
# in Git 1.8.2 (March 2013).
# Built by 'autogen.sh'.
/aclocal.m4
/configure
build-aux/ar-lib
build-aux/compile
build-aux/config.guess
build-aux/config.sub
build-aux/depcomp
build-aux/install-sh
build-aux/missing
lib/Makefile.in
src/config.in
autom4te.cache
# Built by 'configure'.
Info.plist
InfoPlist.strings
Makefile
makefile
!etc/refcards/Makefile
!test/automated/data/flymake/Makefile
!test/indent/Makefile
!test/etags/Makefile
!test/etags/make-src/Makefile
/*.cache
/confdefs.h
/config.status
/configure.lineno
/conftest*
src/config.h
src/epaths.h
# C-level sources built by 'make'.
lib/alloca.h
lib/arg-nonnull.h
lib/byteswap.h
lib/c++defs.h
lib/dirent.h
lib/errno.h
lib/execinfo.h
lib/fcntl.h
lib/getopt.h
lib/inttypes.h
lib/libgnu.a
lib/signal.h
lib/std*.h
!lib/std*.in.h
lib/string.h
lib/sys/
lib/time.h
lib/unistd.h
lib/warn-on-use.h
src/buildobj.h
src/globals.h
src/lisp.mk
# Lisp-level sources built by 'make'.
*cus-load.el
*loaddefs.el
leim/changed.misc
leim/changed.tit
lisp/cedet/semantic/bovine/c-by.el
lisp/cedet/semantic/bovine/make-by.el
lisp/cedet/semantic/bovine/scm-by.el
lisp/cedet/semantic/wisent/javat-wy.el
lisp/cedet/semantic/wisent/js-wy.el
lisp/cedet/semantic/wisent/python-wy.el
lisp/cedet/srecode/srt-wy.el
lisp/eshell/esh-groups.el
lisp/finder-inf.el
lisp/leim/ja-dic/
lisp/leim/leim-list.el
lisp/leim/quail/4Corner.el
lisp/leim/quail/ARRAY30.el
lisp/leim/quail/CCDOSPY.el
lisp/leim/quail/CTLau.el
lisp/leim/quail/CTLau-b5.el
lisp/leim/quail/ECDICT.el
lisp/leim/quail/ETZY.el
lisp/leim/quail/PY-b5.el
lisp/leim/quail/PY.el
lisp/leim/quail/Punct.el
lisp/leim/quail/Punct-b5.el
lisp/leim/quail/QJ.el
lisp/leim/quail/QJ-b5.el
lisp/leim/quail/SW.el
lisp/leim/quail/TONEPY.el
lisp/leim/quail/ZIRANMA.el
lisp/leim/quail/ZOZY.el
lisp/leim/quail/quick-b5.el
lisp/leim/quail/quick-cns.el
lisp/leim/quail/tsang-b5.el
lisp/leim/quail/tsang-cns.el
lisp/subdirs.el
# Dependencies.
.deps/
deps/
# Logs and temporaries.
*.log
*.tmp
# Time stamps.
*.stamp
stamp_BLD
src/gl-stamp
src/stamp-h.in
src/stamp-h1
# Object files and debugging.
*.a
*.dSYM/
*.core
*.elc
*.o
*.res
[0-9]*.core
core
core.*[0-9]
oo/
oo-spd/
src/*.map
# Tests.
test/indent/*.new
test/biditest.txt
test/etags/srclist
test/etags/regexfile
test/etags/ETAGS
test/etags/CTAGS
# ctags, etags.
TAGS
!admin/notes/tags
# GNU global.
GPATH
GSYMS
GRTAGS
GTAGS
# GNU idutils.
ID
# Executables.
*.exe
a.out
lib-src/blessmail
lib-src/ctags
lib-src/ebrowse
lib-src/emacsclient
lib-src/etags
lib-src/hexl
lib-src/make-docfile
lib-src/movemail
lib-src/profile
lib-src/test-distrib
lib-src/update-game-score
nextstep/Cocoa/Emacs.base/Contents/Info.plist
nextstep/Cocoa/Emacs.base/Contents/Resources/English.lproj
nextstep/Emacs.app/
nextstep/GNUstep/Emacs.base/Resources/Emacs.desktop
nextstep/GNUstep/Emacs.base/Resources/Info-gnustep.plist
src/bootstrap-emacs
src/emacs
src/emacs-[0-9]*
src/temacs
# Character-set info.
admin/charsets/jisx2131-filter
admin/unidata/unidata.txt
etc/charsets/*.map
lisp/international/charprop.el
lisp/international/charscript.el
lisp/international/cp51932.el
lisp/international/eucjp-ms.el
lisp/international/uni-*.el
# Documentation.
*.aux
*.cm
*.cms
*.cp
*.cps
*.dvi
*.fn
*.fns
*.info
*.ky
*.kys
*.op
*.ops
*.pdf
!doc/lispintro/cons-*.pdf
!doc/lispintro/drawers.pdf
!doc/lispintro/lambda-*.pdf
!etc/refcards/gnus-logo.pdf
*.pg
*.pgs
*.pj
*.pjs
*.sc
*.scs
*.t2d/
*.tg
*.tgs
*.toc
*.tp
*.tps
*.vr
*.vrs
doc/*/*.html
doc/*/*/*.html
doc/*/*.ps
doc/*/*/*.ps
doc/emacs/emacsver.texi
doc/man/emacs.1
doc/misc/cc-mode.ss
etc/DOC
etc/refcards/emacsver.tex
gnustmp*
/info/
# Version control and locks.
*.orig
*.rej
*~
/README.W32
.#*
\#*\#
ChangeLog
[0-9]*.patch
[0-9]*.txt
/vc-dwim-log-*
# Built by 'make install'.
etc/emacs.tmpdesktop
# Distribution directories.
/emacs-[1-9]*/
# Microsoft-related builds and installations.
*.in-h
_*
!build-aux/snippet/_Noreturn.h
/bin/
/BIN/
/data/
etc/icons/
lib/cxxdefs.h
lib/SYS/
/libexec/
/lock/
/README.W32
/share/
/site-lisp/
/leim/ja-dic/
nt/emacs.rc
nt/emacsclient.rc
src/gdb.ini
/var/
This file contains information on Emacs developer processes.
For information on contributing to Emacs as a non-developer, see
(info "(emacs)Contributing") or
http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
* 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
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. 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.
See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
advanced information.
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
and the committer; use the --author option on the commit command to
specify the actual author; the committer defaults to you.
** Commit messages
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 (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.
Below are some rules and recommendations for formatting commit
messages:
- 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
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 when it comes to
ChangeLogs:
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
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).
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, 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.
** Generating ChangeLog entries
- You can use various Emacs functions to ease the process of writing
ChangeLog entries; see (info "(emacs)Change Log Commands") or
http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
- 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
Development normally takes places on the trunk.
Sometimes specialized features are developed on separate branches
before possibly being merged to the trunk.
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 emacs-devel mailing
list under the "emacs-announce" topic, and not anywhere else.
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
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.
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.
** Other process information
*** 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.
** 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 tracker at http://debbugs.gnu.org .
You can subscribe to the mailing lists, or see the list archives,
by following links from http://savannah.gnu.org/mail/?group=emacs .
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'.
** Document 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.
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 documentation errors before submitting a patch.
** Test your changes.
Please test your changes before committing them or sending them to the
list.
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.
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
<filename>" to run the tests for <filename>.el(c). See
"test/automated/Makefile" for more information.
** Understanding Emacs Internals.