+* How developers contribute to GNU Emacs
- Contributing to Emacs
+Here is how software developers can contribute to Emacs. (Non-developers: see
+http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
+or run the shell command 'info "(emacs)Contributing"'.)
-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.
+** The Emacs repository
-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.
+Emacs development uses Git on Savannah for its main repository.
+Briefly, the following shell commands build and run Emacs from scratch:
-You may also want to submit your change so that can be considered for
-inclusion in a future version of Emacs (see below).
+ git config --global user.name 'Your Name'
+ git config --global user.email 'your.name@example.com'
+ git config --global transfer.fsckObjects true
+ git clone git://git.sv.gnu.org/emacs.git
+ cd emacs
+ ./autogen.sh
+ ./configure
+ make
+ src/emacs
+
+For more details, see
+http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
+http://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
+admin/notes/git-workflow.
+
+** Getting involved with development
+
+You can subscribe to the emacs-devel@gnu.org mailing list, paying
+attention to postings with subject lines containing "emacs-announce",
+as these discuss important events like feature freezes. See
+http://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list
+instructions and archives. You can develop and commit changes in your
+own copy of the repository, and discuss proposed changes on the
+mailing list. Frequent contributors to Emacs can request write access
+there.
-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.
+** Committing changes by others
-Here are some style and legal conventions for contributors to Emacs:
+If committing changes written by someone else, commit in their name,
+not yours. You can use 'git commit --author="AUTHOR"' to specify a
+change's author.
+** Commit messages
-o Coding Standards
+Ordinarily, a change you commit should contain a log entry in its
+commit message and should not touch the repository's ChangeLog files.
+Here is an example commit message (indented):
+
+ Deactivate shifted region
- 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.
+ 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.
- Emacs has certain additional style and coding conventions.
+Occasionally, commit messages are collected and prepended to a
+ChangeLog file, where they can be corrected. It saves time to get
+them right the first time, so here are guidelines for formatting them:
- Ref: http://www.gnu.org/prep/standards_toc.html
- Ref: Standards Info Manual
+- Start with a single unindented summary line explaining the change;
+ do not end this line with a period. If that line starts with a
+ semicolon and a space "; ", the commit 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 for ChangeLogs: see
+ http://www.gnu.org/prep/standards/html_node/Change-Logs.html
+ or run 'info "(standards)Change Logs"'. One exception is that
+ commits still sometimes quote `like-this' (as the standards used to
+ recommend) rather than 'like-this' or ‘like this’ (as they do now),
+ as `...' is so widely used elsewhere in Emacs.
+
+- Some commenting rules in the GNU coding standards 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). See
+ http://www.gnu.org/prep/standards/html_node/Comments.html
+ or run 'info "(standards)Comments"'.
+
+ 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.)
-o Copyright Assignment
+- 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 and MAINTAINERS, or
+ to indicate regeneration of files such as 'lib/gnulib.mk', in the
+ ChangeLog entry. "There is no need" means you don't have to, but
+ you can if you want to.
+
+** Generating 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 Emacs functions to write ChangeLog entries; see
+ http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
+ or run 'info "(emacs)Change Log Commands"'.
+
+- 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.
- Contact us at emacs-devel@gnu.org to obtain the relevant
- forms.
+- 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
-o Getting the Source Code
+Future development normally takes place on the master branch.
+Sometimes specialized features are developed on other branches before
+possibly being merged to the master. Release branches are named
+"emacs-NN" where NN is the major version number, and are mainly
+intended for more-conservative changes such as bug fixes. Typically,
+collective development is active on the master branch and possibly on
+the current release branch. Periodically, the current release branch
+is merged into the master, using the gitmerge function described in
+admin/notes/git-workflow.
- 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.
-
- Ref: http://savannah.gnu.org/projects/emacs
+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 by the gitmerge function.
+However, if you know that the change will be difficult to merge to the
+master (e.g., because the code on master has changed a lot), you can
+apply the change to both master 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,
+say in the release branch commit message that there is no need to merge
+the commit to master, by starting the commit message with "Backport:".
+The gitmerge function excludes these commits from the merge to the master.
-o Submitting Patches
+Some changes should not be merged to master at all, for whatever
+reasons. These should be marked by including something like "Do not
+merge to master" or anything that matches gitmerge-skip-regexp (see
+admin/gitmerge.el) in the commit message.
- Every patch must have several pieces of information before we
- can properly evaluate it.
+** Other process information
- For bug fixes, a description of the bug and how your patch fixes
- this bug.
+** Emacs Mailing lists.
- For new features, a description of the feature and your
- implementation.
+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 http://debbugs.gnu.org tracker.
- 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.
+The Savannah info page http://savannah.gnu.org/mail/?group=emacs
+describes how to subscribe to the mailing lists, or see the list
+archives.
- Ref: Change Log Concepts node of the Standards Info Manual
+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'.
- 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.
+** Issue tracker (a.k.a. "bug tracker")
- We accept patches as plain text (preferred for the compilers
- themselves), MIME attachments (preferred for the web pages), or
- as uuencoded gzipped text.
+The Emacs issue tracker at http://debbugs.gnu.org lets you 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.
- 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.
+GNU ELPA has a 'debbugs' package that allows accessing the tracker
+database from Emacs.
+** Documenting your changes
-o Please reread your patch before submitting it.
+Any change that matters to end-users should have an entry in etc/NEWS.
+Doc-strings should be updated together with the code.
-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.
-
+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.
-o Supplemental information for Emacs Developers:
+For more specific tips on Emacs's doc style, see
+http://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
+Use 'checkdoc' to check for documentation errors before submitting a patch.
- Once you become a frequent contributor to Emacs, we can
- consider giving you write access to the CVS repository.
-
- Discussion about Emacs development takes place on
- emacs-devel@gnu.org.
+** Testing 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).
- 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.
+Emacs uses ERT, Emacs Lisp Regression Testing, for testing. See
+http://www.gnu.org/software/emacs/manual/html_node/ert/
+or run 'info "(ert)"' for for more information on writing and running
+tests.
- The file DEBUG describes how to debug Emacs bugs.
+If your test lasts longer than some few seconds, mark it in its
+'ert-deftest' definition with ":tags '(:expensive-test)".
- Avoid using `defadvice' or `eval-after-load' for Lisp
- code to be included in Emacs.
+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/README"
+for more information.
+
+** Understanding Emacs internals
+
+The best way to understand Emacs internals is to read the code. Some
+source files, such as xdisp.c, have extensive comments describing the
+design and implementation. The following resources may also help:
+
+http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
+http://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html
+
+or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
+
+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, use the
+UTF-8 encoding unless it cannot do the job for some good reason.
+Although it is generally a good idea to add 'coding:' cookies to
+non-ASCII source files, cookies are not needed in UTF-8-encoded *.el
+files intended for use only with Emacs version 24.5 and later.
+
+*** 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 the master branch, instead of 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
+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]*$"
+coding: utf-8
+end: