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. ** 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 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. ** 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 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. - 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): * kmacro.el (kmacro-edit-lossage): * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys. (Rather than anything involving "ditto" and suchlike.) - 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. 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 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 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 info-gnu-emacs mailing list, 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 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. 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 . Local variables: mode: outline paragraph-separate: "[ ]*$" end: