-Copyright (C) 2006-2014 Free Software Foundation, Inc.
-See end for license conditions.
+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
- Contributing to Emacs
-
-Emacs is a collaborative project and we encourage contributions from
-anyone and everyone. If you want to contribute in the way that will
-help us most, we recommend (1) fixing reported bugs and (2)
-implementing the feature ideas in etc/TODO. However, if you think of
-new features to add, please suggest them too -- we might like your
-idea. Porting to new platforms is also useful, when there is a new
-platform, but that is not common nowadays.
-
-For documentation on Emacs (to understand how to implement your
-desired change), refer to:
-
-- the Emacs Manual
- http://www.gnu.org/software/emacs/manual/emacs.html
- (info "(Emacs)Top")
-
-- the Emacs Lisp Reference Manual
- http://www.gnu.org/software/emacs/manual/elisp.html
- (info "(elisp)Top")
-
-- http://www.gnu.org/software/emacs
-
-- http://www.emacswiki.org/
-
-There are many ways to contribute to Emacs:
-
-- implement a new feature, and submit a patch (see "Submitting
- Patches" below).
-
-- answer questions on the Emacs user mailing list
- https://lists.gnu.org/mailman/listinfo/help-gnu-emacs
-
-- write documentation, either on the wiki, or in the Emacs source
- repository (see "Submitting Patches" below)
-
-- find and report bugs; use M-x report-emacs-bug
-
-- check if existing bug reports are fixed in newer versions of Emacs
- http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs
-
-- develop a package that works with Emacs, and publish it on your own
- or in Gnu ELPA (see admin/notes/elpa).
-
-Here are some style and legal conventions for contributors to Emacs:
-
-
-* Coding Standards
-
-Contributed code should follow the GNU Coding Standards
-(http://www.gnu.org/prep/standards/ - may also be available in info on
-your system).
-
-If it doesn't, we'll need to find someone to fix the code before we
-can use it.
-
-Emacs has additional style and coding conventions:
-
-- the "Tips" Appendix in the Emacs Lisp Reference
- http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
- (info "(elisp)Tips").
-
-- Avoid using `defadvice' or `eval-after-load' for Lisp code to be
- included in Emacs.
-
-- Remove all trailing whitespace in all source and text files.
-
-- Emacs has no convention on whether to use tabs in source code;
- please don't change whitespace in the files you edit.
-
-- Use ?\s instead of ? in Lisp code for a space character.
-
-* Copyright Assignment
-
-The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
-The FSF is a nonprofit with a worldwide mission to promote computer
-user freedom and to defend the rights of all free software users.
-For general information, see the website http://www.fsf.org/ .
-
-Generally speaking, for non-trivial contributions to GNU Emacs we
-require that the copyright be assigned to the FSF. For the reasons
-behind this, see: http://www.gnu.org/licenses/why-assign.html .
-
-Copyright assignment is a simple process. Residents of some countries
-can do it entirely electronically. We can help you get started, and
-answer any questions you may have (or point you to the people with the
-answers), at the emacs-devel@gnu.org mailing list.
-
-(Please note: general discussion about why some GNU projects ask
-for a copyright assignment is off-topic for emacs-devel.
-See gnu-misc-discuss instead.)
-
-A copyright disclaimer is also a possibility, but we prefer an assignment.
-Note that the disclaimer, like an assignment, involves you sending
-signed paperwork to the FSF (simply saying "this is in the public domain"
-is not enough). Also, a disclaimer cannot be applied to future work, it
-has to be repeated each time you want to send something new.
-
-We can accept small changes (roughly, fewer than 15 lines) without
-an assignment. This is a cumulative limit (e.g. three separate 5 line
-patches) over all your contributions.
-
-* Getting the Source Code
-
-The current working version of the Emacs source code is stored in a
-git repository on the Savannah web site
-(http://savannah.gnu.org/projects/emacs). It is important to write
-your patch based on the current working version. If you start from an
-older version, your patch may be outdated (so that maintainers will
-have a hard time applying it), or changes in Emacs may have made your
-patch unnecessary.
-
-After you have downloaded the repository source, you should read the file
-INSTALL.REPO for build instructions (they differ to some extent from a
-normal build).
-
-* Submitting Patches
-
-Every patch must have several pieces of information before we
-can properly evaluate it.
-
-When you have all these pieces, bundle them up in a mail message and
-send it to the developers. Sending it to bug-gnu-emacs@gnu.org
-(which is the bug/feature list) is recommended, because that list
-is coupled to a tracking system that makes it easier to locate patches.
-If your patch is not complete and you think it needs more discussion,
-you might want to send it to emacs-devel@gnu.org instead. If you
-revise your patch, send it as a followup to the initial topic.
-
-** Description
-
-For bug fixes, a description of the bug and how your patch fixes it.
-
-For new features, a description of the feature and your implementation.
-
-** ChangeLog
-
-A ChangeLog entry as plaintext (separate from the patch).
-
-See the existing ChangeLog files for format and content. Note that,
-unlike some other projects, we do require ChangeLogs for
-documentation, i.e. Texinfo files.
-
-Ref: "Change Log Concepts" node of the GNU Coding Standards Info
-Manual, for how to write good log entries.
-http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
-
-When using git, commit messages should use ChangeLog format, with a
-single short line explaining the change, then an empty line, then
-unindented ChangeLog entries. (Essentially, a commit message should
-be a duplicate of what the patch adds to the ChangeLog files. We are
-planning to automate this better, to avoid the duplication.) You can
-use the Emacs functions log-edit-add-to-changelog or
-log-edit-insert-changelog to ease this process.
-
-** The patch itself.
-
-If you are accessing the Emacs repository, make sure your copy is
-up-to-date (e.g. with 'git pull'). You can commit your changes
-to a private branch and generate a patch from the master version
-by using
- git format-patch master
-Or you can leave your changes uncommitted and use
- git diff
-With no repository, you can use
- diff -u OLD NEW
-
-** Mail format.
-
-We prefer to get the patches as plain text, either inline (be careful
-your mail client does not change line breaks) or as MIME attachments.
-
-** Please reread your patch before submitting it.
-
-** Do not mix changes.
-
-If you send several unrelated changes together, we will ask you to
-separate them so we can consider each of the changes by itself.
-
-** Do not make formatting changes.
-
-Making cosmetic formatting changes (indentation, etc) makes it harder
-to see what you have really changed.
-
-
-* Supplemental information for Emacs Developers.
+* Information for Emacs Developers.
An "Emacs Developer" is someone who contributes a lot of code or
-documentation to the Emacs repository.
+documentation to the Emacs repository. Generally, they have write
+access to the Emacs git repository on Savannah.
** Write access to the Emacs repository.
and the committer; use the --author option on the commit command to
specify the actual author; the committer defaults to you.
+** commit messages
+
+When using git, commit messages should use ChangeLog format, with the
+following modifications:
+
+- Add a single short line explaining the change, then an empty line,
+ then unindented ChangeLog entries.
+
+ You can use various Emacs functions to ease this process; see (info
+ "(emacs)Change Log Commands") or
+ http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
+
+- The summary line is limited to 72 characters (enforced by a commit
+ hook). If you have trouble making that a good summary, add a
+ paragraph below it, 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.
+
+- 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.
+
** Changelog notes
- Emacs generally follows the GNU coding standards when it comes to
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).
+
+ It is tempting to relax this rule for commit messages, since they
+ are somewhat transient. However, they are preserved indefinitely,
+ and have a reasonable chance of being read in the future, so it's
+ better that they have good presentation.
+
- There are multiple ChangeLogs in the emacs source; roughly one per
high-level directory. The ChangeLog entry for a commit belongs in the
lowest ChangeLog that is higher than or at the same level as any file
changed by the commit.
+- Use the present tense; describe "what the change does", not "what
+ the change did".
+
- Preferred form for several entries with the same content:
* help.el (view-lossage):
(Rather than anything involving "ditto" and suchlike.)
-- In ChangeLog files, there is no standard or recommended way to
+- If the commit fixes a bug, add 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.
One way to identify revisions is by quoting their summary line.
"2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
will suffice.
-- There is no need to make separate change log entries for files such
+- There is no need to make separate ChangeLog entries for files such
as NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration
of files such as 'configure'. "There is no need" means you don't
have to, but you can if you want to.
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
-You must follow emacs-devel to know exactly what kinds of changes are
-allowed on what branch at any time. Announcements about the freeze
-(and other important events) will contain "ANNOUNCE" in the subject.
+Announcements about the freeze (and other important events) are made
+on the info-gnu-emacs mailing list.
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
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.
work in the best of circumstances, and we can't keep up unless you do
your best to help.
+Every patch must have several pieces of information before we
+can properly evaluate it.
+
+When you have all these pieces, bundle them up in a mail message and
+send it to the developers. Sending it to
+@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is
+recommended, because that list is coupled to a tracking system that
+makes it easier to locate patches. If your patch is not complete and
+you think it needs more discussion, you might want to send it to
+@email{emacs-devel@@gnu@@gnu.org} instead. If you revise your patch,
+send it as a followup to the initial topic.
+
+We prefer to get the patches as plain text, either inline (be careful
+your mail client does not change line breaks) or as MIME attachments.
+
@itemize @bullet
@item
-Send an explanation with your changes of what problem they fix or what
-improvement they bring about. For a fix for an existing bug, it is
+Include an explanation with your changes of what problem they fix or what
+improvement they bring about.
+
+@itemize
+@item
+For a fix for an existing bug, it is
best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
list, or the bug entry in the GNU Bug Tracker at
@url{http://debbugs.gnu.org}. Explain why your change fixes the bug.
@item
-Always include a proper bug report for the problem you think you have
-fixed. We need to convince ourselves that the change is right before
-installing it. Even if it is correct, we might have trouble
-understanding it if we don't have a way to reproduce the problem.
+For a new feature, include a description of the feature and your
+implementation.
+
+@item
+For a new bug, include a proper bug report for the problem you think
+you have fixed. We need to convince ourselves that the change is
+right before installing it. Even if it is correct, we might have
+trouble understanding it if we don't have a way to reproduce the
+problem.
+@end itemize
@item
Include all the comments that are appropriate to help people reading the
is important.
@item
+The patch itself.
+
Use @samp{diff -c} to make your diffs. Diffs without context are hard
to install reliably. More than that, they are hard to study; we must
always study a patch to decide whether we want to install it. Unidiff
making diffs of C code. This shows the name of the function that each
change occurs in.
+If you are using the Emacs repository, make sure your copy is
+up-to-date (e.g. with @code{git pull}). You can commit your changes
+to a private branch and generate a patch from the master version by
+using @code{git format-patch master}. Or you can leave your changes
+uncommitted and use @code{git diff}.
+
@item
Avoid any ambiguity as to which is the old version and which is the new.
Please make the old version the first argument to diff, and the new
explanation in comments in the code. It will be more useful there.
Please look at the change log entries of recent commits to see what
-sorts of information to put in, and to learn the style that we use.
-@xref{Change Log}.
+sorts of information to put in, and to learn the style that we use. Note that,
+unlike some other projects, we do require change logs for
+documentation, i.e. Texinfo files.
+@xref{Change Log},
+@ifset WWW_GNU_ORG
+see
+@url{http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
+@end ifset
+@xref{Change Log Concepts, Change Log Concepts,
+Change Log Concepts, gnu-coding-standards, GNU Coding Standards}.
@item
When you write the fix, keep in mind that we can't install a change that
form that is clearly safe to install.
@end itemize
-@c FIXME: Include the node above?
@node Contributing
@section Contributing to Emacs Development
@cindex contributing to Emacs
+Emacs is a collaborative project and we encourage contributions from
+anyone and everyone.
+
+There are many ways to contribute to Emacs:
+
+@itemize
+@item
+find and report bugs; @xref{Bugs}.
+
+@item
+answer questions on the Emacs user mailing list
+@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
+
+@item
+write documentation, either on the wiki, or in the Emacs source
+repository (@pxref{Sending Patches}).
+
+@item
+check if existing bug reports are fixed in newer versions of Emacs
+@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
+
+@item
+fix existing bug reports
+@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
+
+@item
+@c etc/TOOD not in WWW_GNU_ORG
+implement a feature listed in the @file{etc/TODO} file in the Emacs
+distribution, and submit a patch.
+
+@item
+implement a new feature, and submit a patch.
+
+@item
+develop a package that works with Emacs, and publish it on your own
+or in Gnu ELPA (@url{https://elpa.gnu.org/}).
+
+@item
+port Emacs to a new platform, but that is not common nowadays.
+
+@end itemize
+
If you would like to work on improving Emacs, please contact the maintainers at
@ifnothtml
@email{emacs-devel@@gnu.org}.
before you start; it might be possible to suggest ways to make your
extension fit in better with the rest of Emacs.
+When implementing a feature, please follow the Emacs coding standards;
+@xref{Coding Standards}. In addition, non-trivial contributions
+require a copyright assignment to the FSF; @xref{Copyright Assignment}.
+
The development version of Emacs can be downloaded from the
repository where it is actively maintained by a group of developers.
See the Emacs project page
-@url{http://savannah.gnu.org/projects/emacs/} for details.
+@url{http://savannah.gnu.org/projects/emacs/} for access details.
+
+It is important to write your patch based on the current working
+version. If you start from an older version, your patch may be
+outdated (so that maintainers will have a hard time applying it), or
+changes in Emacs may have made your patch unnecessary. After you have
+downloaded the repository source, you should read the file
+@file{INSTALL.REPO} for build instructions (they differ to some extent
+from a normal build).
+
+If you would like to make more extensive contributions, see the
+@file{./CONTRIBUTE} file in the Emacs distribution for information on
+how to be an Emacs developer.
+
+For documentation on Emacs (to understand how to implement your
+desired change), refer to:
+
+@itemize
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the Emacs Manual
+@url{http://www.gnu.org/software/emacs/manual/emacs.html}.
+@end ifhtml
+@ifnothtml
+@xref{Top, Emacs Manual,,emacs}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Top, Emacs Manual,,emacs}.
+@end ifclear
+
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the Emacs Lisp Reference Manual
+@url{http://www.gnu.org/software/emacs/manual/elisp.html}.
+@end ifhtml
+@ifnothtml
+@xref{Top, Emacs Lisp Reference Manual,,elisp}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Top, Emacs Lisp Reference Manual,,elisp}.
+@end ifclear
+
+@item
+@url{http://www.gnu.org/software/emacs}
+
+@item
+@url{http://www.emacswiki.org/}
+@end itemize
+
+@menu
+* Coding Standards:: Gnu Emacs coding standards
+* Copyright Assignment:: assigning copyright to the FSF
+@end menu
-For more information on how to contribute, see the
+@node Coding Standards
+@subsection Coding Standards
+@cindex coding standards
+
+Contributed code should follow the GNU Coding Standards
+@url{http://www.gnu.org/prep/standards/}. This may also be available
+in info on your system.
+
+If it doesn't, we'll need to find someone to fix the code before we
+can use it.
+
+Emacs has additional style and coding conventions:
+
+@itemize
+@item
@ifset WWW_GNU_ORG
@ifhtml
-@url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE}
+the "Tips" Appendix in the Emacs Lisp Reference
+@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}.
@end ifhtml
@ifnothtml
-@file{etc/CONTRIBUTE}
+@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
+Appendix, elisp, Emacs Lisp Reference}.
@end ifnothtml
@end ifset
@ifclear WWW_GNU_ORG
-@file{etc/CONTRIBUTE}
+@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
+Appendix, elisp, Emacs Lisp Reference}.
@end ifclear
-file in the Emacs distribution.
+
+@item
+Avoid using @code{defadvice} or @code{eval-after-load} for Lisp code
+to be included in Emacs.
+
+@item
+Remove all trailing whitespace in all source and text files.
+
+@item
+Emacs has no convention on whether to use tabs in source code; please
+don't change whitespace in the files you edit.
+
+@item
+Use @code{?\s} instead of @code{? } in Lisp code for a space character.
+
+@end itemize
+
+@node Copyright Assignment
+@subsection Copyright Assignment
+@cindex copyright assignment
+
+The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
+The FSF is a nonprofit with a worldwide mission to promote computer
+user freedom and to defend the rights of all free software users.
+For general information, see the website @url{http://www.fsf.org/}.
+
+Generally speaking, for non-trivial contributions to GNU Emacs we
+require that the copyright be assigned to the FSF. For the reasons
+behind this, see @url{http://www.gnu.org/licenses/why-assign.html}.
+
+Copyright assignment is a simple process. Residents of some countries
+can do it entirely electronically. We can help you get started, and
+answer any questions you may have (or point you to the people with the
+answers), at the @email{emacs-devel@@gnu.org} mailing list.
+
+(Please note: general discussion about why some GNU projects ask
+for a copyright assignment is off-topic for emacs-devel.
+See gnu-misc-discuss instead.)
+
+A copyright disclaimer is also a possibility, but we prefer an assignment.
+Note that the disclaimer, like an assignment, involves you sending
+signed paperwork to the FSF (simply saying "this is in the public domain"
+is not enough). Also, a disclaimer cannot be applied to future work, it
+has to be repeated each time you want to send something new.
+
+We can accept small changes (roughly, fewer than 15 lines) without
+an assignment. This is a cumulative limit (e.g. three separate 5 line
+patches) over all your contributions.
@node Service
@section How To Get Help with GNU Emacs
@cindex help-gnu-emacs mailing list
@cindex gnu.emacs.help newsgroup
-If you need help installing, using or changing GNU Emacs, there are two
-ways to find it:
+If you need help installing, using or changing GNU Emacs, there are
+two ways to find it:
@itemize @bullet
@item
projects / emacs.git / commitdiff