-Copyright (C) 2006, 2007, 2008 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
+* Information for Emacs Developers.
-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.
+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.
-For documentation on how to develop Emacs changes, refer to the Emacs
-Manual and the Emacs Lisp Reference Manual (both included in the Emacs
-distribution). The web pages in http://www.gnu.org/software/emacs
-contain additional information.
+** Write access to the Emacs repository.
-You may also want to submit your change so that can be considered for
-inclusion in a future version of Emacs (see below).
+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.
-If you don't feel up to hacking Emacs, there are many other ways to
-help. You can answer questions on the mailing lists, write
-documentation, find and report bugs, contribute to the Emacs web
-pages, or develop a package that works with Emacs.
+** Using the Emacs repository
-Here are some style and legal conventions for contributors to Emacs:
+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.
-* Coding Standards
+Alternately, see admin/notes/git-workflow.
-Contributed code should follow the GNU Coding Standard.
+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.
-If it doesn't, we'll need to find someone to fix the code before we
-can use it.
+** Commit messages
-Emacs has certain additional style and coding conventions.
+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):
-Ref: http://www.gnu.org/prep/standards_toc.html
-Ref: GNU Coding Standards Info Manual
-Ref: The "Tips" Appendix in the Emacs Lisp Reference.
+ 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.
-* Copyright Assignment
+Below are some rules and recommendations for formatting commit
+messages:
-We can accept small changes without legal papers, and for medium-size
-changes a copyright disclaimer is ok too. To accept substantial
-contributions from you, we need a copyright assignment form filled out
-and filed with the FSF.
+- 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.
-Contact us at emacs-devel@gnu.org to obtain the relevant forms.
+- 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.
-* Getting the Source Code
+- 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.
-The latest version of Emacs can be downloaded using CVS or Arch from
-the Savannah web site. It is important to write your patch based on
-this version; if you start from an older version, your patch may be
-outdated when you write it, and maintainers will have hard time
-applying it.
+- If the commit has more than one author, the commit message should
+ contain separate lines to mention the other authors, like the
+ following:
-After you have downloaded the CVS source, you should read the file
-INSTALL.CVS for build instructions (they differ to some extent from a
-normal build).
+ Co-authored-by: Joe Schmoe <j.schmoe@example.org>
-Ref: http://savannah.gnu.org/projects/emacs
+- 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
-* Submitting Patches
+- 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.
-Every patch must have several pieces of information before we
-can properly evaluate it.
+- Commit messages should not contain the "Signed-off-by:" lines that
+ are used in some other projects.
-When you have all these pieces, bundle them up in a mail message and
-send it to emacs-pretest-bug@gnu.org or emacs-devel@gnu.org.
+- Any lines of the commit message that start with "; " are omitted
+ from the generated ChangeLog.
-All subsequent discussion should also be sent to the mailing list.
+- 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.
-** Description
+- 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.
-For bug fixes, a description of the bug and how your patch fixes this
-bug.
+- 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).
-For new features, a description of the feature and your
-implementation.
+ They are preserved indefinitely, and have a reasonable chance of
+ being read in the future, so it's better that they have good
+ presentation.
-** ChangeLog
+- Use the present tense; describe "what the change does", not "what
+ the change did".
-A ChangeLog entry as plaintext (separate from the patch).
+- Preferred form for several entries with the same content:
-See the various ChangeLog files for format and content. Note that,
-unlike some other projects, we do require ChangeLogs also for
-documentation, i.e. Texinfo files.
+ * lisp/help.el (view-lossage):
+ * lisp/kmacro.el (kmacro-edit-lossage):
+ * lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
-Ref: "Change Log Concepts" node of the GNU Coding Standards Info
-Manual, for how to write good log entries.
+ (Rather than anything involving "ditto" and suchlike.)
-** The patch itself.
+- 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.
-Please use "Context Diff" format.
+ 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.
-If you are accessing the CVS repository use
- cvs update; cvs diff -cp
-else, use
- diff -cp OLD NEW
+- 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.
-If your version of diff does not support these options, then get the
-latest version of GNU Diff.
+** Generating ChangeLog entries
-** Mail format.
+- 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.
-We prefer to get the patches as inline plain text.
+- 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.
-Please be aware of line wrapping which will make the patch unreadable
-and useless for us. To avoid that, you can use MIME attachments or,
-as a last resort, uuencoded gzipped text.
+- 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.
-** Please reread your patch before submitting it.
+** Branches
-** Do not mix changes.
+Development normally takes places on the trunk.
+Sometimes specialized features are developed on separate branches
+before possibly being merged to the trunk.
-If you send several unrelated changes together, we will ask you to
-separate them so we can consider each of the changes by itself.
+Development is discussed on the emacs-devel mailing list.
+The trunk branch is named "master" in git; release branches are named
+"emacs-nn" where "nn" is the major version.
-* Coding style and conventions.
+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.
-** Mandatory reading:
+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. 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.
-The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
-** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
-included in Emacs.
+** Other process information
-** Remove all trailing whitespace in all source and text files.
+** Emacs Mailing lists.
-** Use ?\s instead of ? in Lisp code for a space character.
+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 .
-* Supplemental information for Emacs Developers.
+You can subscribe to the mailing lists, or see the list archives,
+by following links from http://savannah.gnu.org/mail/?group=emacs .
-** Write access to Emacs' CVS repository.
+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'.
-Once you become a frequent contributor to Emacs, we can consider
-giving you write access to the CVS repository.
+** 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.
-** Emacs Mailing lists.
+GNU ELPA has a 'debbugs' package that allows accessing the tracker
+database from Emacs.
-Discussion about Emacs development takes place on emacs-devel@gnu.org.
+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/triage.
-Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
+** Document your changes.
-Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
+Any change that matters to end-users should have an entry in etc/NEWS.
-You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
+Doc-strings should be updated together with the code.
-You can find the mailing lists archives at lists.gnu.org or gmane.org.
+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.
-** Document your changes.
+** Test your changes.
-Think carefully about whether your change requires updating the
-documentation. If it does, you can either do this yourself or add an
-item to the NEWS file.
+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).
-If you document your change in NEWS, please mark the NEWS entry with
-the documentation status of the change: if you submit the changes for
-the manuals, mark it with "+++"; if it doesn't need to be documented,
-mark it with "---"; if it needs to be documented, but you didn't
-submit documentation changes, leave the NEWS entry unmarked. (These
-marks are checked by the Emacs maintainers to make sure every change
-was reflected in the manuals.)
+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/". From the "test/" directory, run "make
+<filename>" to run the tests for <filename>.el(c). See
+"test/Makefile" for more information.
** 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.
-* How to Maintain Copyright Years for GNU Emacs
+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.
-See admin/notes/copyright.
+*** git vs rename
-** Our lawyer says it is ok if we add, to each file that has been in Emacs
-since Emacs 21 came out in 2001, all the subsequent years. We don't
-need to check whether *that file* was changed in those years.
-It's sufficient that *Emacs* was changed in those years (and it was!).
+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:
-** For those files that have been added since then, we should add
-the year it was added to Emacs, and all subsequent years.
+- create a feature branch
-** For the refcards under etc/, it's ok to simply use the latest year
-(typically in a `\def\year{YEAR}' expression) for the rendered copyright
-notice, while maintaining the full list of years in the copyright notice
-in the comments.
+- 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.
-GNU Emacs is free software; you can redistribute it and/or modify
+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, or (at your option)
-any later version.
+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
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
-along with GNU Emacs; see the file COPYING. If not, write to the
-Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
-Boston, MA 02110-1301, USA.
+along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
\f
Local variables:
mode: outline
paragraph-separate: "[ \f]*$"
end:
-