+This file contains information on Emacs developer processes.
- Contributing to Emacs
+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
-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.
+* Information for Emacs Developers.
-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.
+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.
-You may also want to submit your change so that can be considered for
-inclusion in a future version of Emacs (see below).
+** Write access to the Emacs repository.
-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.
+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.
-Here are some style and legal conventions for contributors to Emacs:
+** Using the Emacs repository
+Emacs uses git for the source code repository.
-o Coding Standards
+See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
+started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
+advanced information.
- Contributed code should follow the GNU Coding Standard.
- If it doesn't, we'll need to find someone to fix the code
- before we can use it.
+Alternately, see admin/notes/git-workflow.
- Emacs has certain additional style and coding conventions.
+If committing changes written by someone else, make the ChangeLog
+entry 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.
- Ref: http://www.gnu.org/prep/standards_toc.html
- Ref: Standards Info Manual
+** commit messages
+When using git, commit messages should use ChangeLog format, with the
+following modifications:
-o Copyright Assignment
+- Add a single short line explaining the change, then an empty line,
+ then unindented ChangeLog entries.
- We can accept small changes without legal papers, and for
- medium-size changes a copyright disclaimer is ok too. Toa
- accept substantial contributions from you, we need a copyright
- assignment form filled out and filed with the FSF.
+ 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.
- Contact us at emacs-devel@gnu.org to obtain the relevant
- forms.
+- 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.
-o Getting the Source Code
+- 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.
- 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 this version; if you start from an older
- version, your patch may be outdated when you write it.
+** ChangeLog notes
- After you have downloaded the source, you should read the file
- INSTALL.CVS for further instructions.
+- Emacs generally follows the GNU coding standards when it comes to
+ ChangeLogs:
+ http://www.gnu.org/prep/standards/html_node/Change-Logs.html . 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.
- Ref: http://savannah.gnu.org/projects/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.
-o Submitting Patches
+- 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.
- Every patch must have several pieces of information before we
- can properly evaluate it.
+- Use the present tense; describe "what the change does", not "what
+ the change did".
- For bug fixes, a description of the bug and how your patch fixes
- this bug.
+- Preferred form for several entries with the same content:
- For new features, a description of the feature and your
- implementation.
+ * help.el (view-lossage):
+ * kmacro.el (kmacro-edit-lossage):
+ * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
- A ChangeLog entry as plaintext (separate from the patch); 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.
+ (Rather than anything involving "ditto" and suchlike.)
- Ref: Change Log Concepts node of the Standards Info Manual
+- If the commit fixes a bug, add a separate line
- The patch itself. If you are accessing the CVS repository use
- "cvs update; cvs diff -cp"; else, use "diff -cp OLD NEW". If
- your version of diff does not support these options, then get
- the latest version of GNU diff.
+ Fixes: bug#NNNN
- We accept patches as plain text (preferred for the compilers
- themselves), MIME attachments (preferred for the web pages), or
- as uuencoded gzipped text.
+ where NNNN is the bug number.
- 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.
- All subsequent discussion should also be sent to the mailing
- list.
+- In ChangeLog entries, there is no standard or recommended way to
+ identify revisions.
+ 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.
-o Please reread your patch before submitting it.
+- 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.
+** branches
-o 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 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.
-o Supplemental information for Emacs Developers:
+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 info-gnu-emacs mailing
+list, and not anywhere else.
- Once you become a frequent contributor to Emacs, we can
- consider giving you write access to the CVS repository.
+The trunk branch is named "master" in git; release branches are named
+"emacs-nn" where "nn" is the major version.
- Discussion about Emacs development takes place on
- emacs-devel@gnu.org.
+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.
- 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.
+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.
- 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.
- The file DEBUG describes how to debug Emacs bugs.
+** Other process information
- Avoid using `defadvice' or `eval-after-load' for Lisp
- code to be included in Emacs.
+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.
+
+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 .
+
+** 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.
+
+** 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.
+
+The file etc/DEBUG describes how to debug Emacs bugs.
+
+
+\f
+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/>.
+\f
+Local variables:
+mode: outline
+paragraph-separate: "[ \f]*$"
+end: