-Copyright (C) 2006, 2007 Free Software Foundation, Inc.
+Copyright (C) 2006-2014 Free Software Foundation, Inc.
See end for license conditions.
idea. Porting to new platforms is also useful, when there is a new
platform, but that is not common nowadays.
-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.
+For documentation on Emacs (to understand how to implement your
+desired change), refer to:
-You may also want to submit your change so that can be considered for
-inclusion in a future version of Emacs (see below).
+- the Emacs Manual
+ http://www.gnu.org/software/emacs/manual/emacs.html
+ (info "(Emacs)Top")
-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.
+- 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 Standard.
+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 certain additional style and coding conventions.
+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").
-Ref: http://www.gnu.org/prep/standards_toc.html
-Ref: GNU Coding Standards Info Manual
-Ref: The "Tips" Appendix in the Emacs Lisp Reference.
+- 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
-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.
+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/ .
-Contact us at emacs-devel@gnu.org to obtain the relevant forms.
+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.
-* Getting the Source Code
+(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.)
-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.
+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.
-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).
+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
-Ref: http://savannah.gnu.org/projects/emacs
+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
can properly evaluate it.
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.
+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 this
-bug.
+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.
+For new features, a description of the feature and your implementation.
** ChangeLog
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
+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
-** The patch itself.
-
-Please use "Context Diff" format.
+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.
-If you are accessing the CVS repository use
- cvs update; cvs diff -cp
-else, use
- diff -cp OLD NEW
+** The patch itself.
-If your version of diff does not support these options, then get the
-latest version of GNU Diff.
+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 inline plain text.
-
-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.
+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.
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.
-* Coding style and conventions.
+Making cosmetic formatting changes (indentation, etc) makes it harder
+to see what you have really changed.
-** Mandatory reading:
-The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
+* Supplemental information for Emacs Developers.
-** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
-included in Emacs.
+An "Emacs Developer" is someone who contributes a lot of code or
+documentation to the Emacs repository.
-** Remove all trailing whitespace in all source and text files.
+** Write access to the Emacs repository.
-** Use ?\s instead of ? in Lisp code for a space character.
+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
-* Supplemental information for Emacs Developers.
+Emacs uses git for the source code repository.
-** Write access to Emacs' CVS repository.
+See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
+started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
+advanced information.
-Once you become a frequent contributor to Emacs, we can consider
-giving you write access to the CVS repository.
+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.
-** Emacs Mailing lists.
+** Changelog notes
-Discussion about Emacs development takes place on emacs-devel@gnu.org.
+- 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.
-Bug reports for released versions are sent to bug-gnu-emacs@gnu.org.
+- 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.
-Bug reports for development versions are sent to emacs-pretest-bug@gnu.org.
+- Preferred form for several entries with the same content:
-You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs.
+ * help.el (view-lossage):
+ * kmacro.el (kmacro-edit-lossage):
+ * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
-You can find the mailing lists archives at lists.gnu.org or gmane.org.
+ (Rather than anything involving "ditto" and suchlike.)
+- In ChangeLog files, there is no standard or recommended way to
+ identify revisions.
-** Document your changes.
+ 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.
-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.
+- There is no need to make separate change log 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.
-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.)
+** branches
+Development normally takes places on the trunk.
+Sometimes specialized features are developed on separate branches
+before possibly being merged to the trunk.
-** Understanding Emacs Internals.
+Development is discussed on the emacs-devel mailing list.
-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.
+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. This freeze is announced on the
+emacs-devel mailing list, and not anywhere else.
-The file etc/DEBUG describes how to debug Emacs bugs.
+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.
+
+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.
+** Emacs Mailing lists.
-* How to Maintain Copyright Years for GNU Emacs
+Discussion about Emacs development takes place on emacs-devel@gnu.org.
-See admin/notes/copyright.
+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 .
-** 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!).
+You can subscribe to the mailing lists, or see the list archives,
+by following links from http://savannah.gnu.org/mail/?group=emacs .
-** For those files that have been added since then, we should add
-the year it was added to Emacs, and all subsequent years.
+** Document your changes.
-** 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.
+Any change that matters to end-users should have an entry in etc/NEWS.
+
+Think about whether your change requires updating the documentation
+(both manuals and doc-strings). 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
+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:
-