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, check if existing bug reports
-are fixed in newer versions of Emacs, 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.
Here are some style and legal conventions for contributors to Emacs:
* Coding Standards
-Contributed code should follow the GNU Coding Standards.
+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/
-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, but
+ please don't change whitespace in the files you edit.
+
+- Use ?\s instead of ? in Lisp code for a space character.
* Copyright Assignment
* Getting the Source Code
-The latest version of the Emacs source code can be downloaded from the
-Savannah web site. It is important to write your patch based on the
-latest 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.
+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).
-Ref: http://savannah.gnu.org/projects/emacs
-
-
* Submitting Patches
Every patch must have several pieces of information before we
A ChangeLog entry as plaintext (separate from the patch).
See the existing ChangeLog files for format and content. Note that,
-unlike some other projects, we do require ChangeLogs also for
+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
When using git, commit messages should use ChangeLog format, with a
single short line explaining the change, then an empty line, then
to see what you have really changed.
-* Coding style and conventions.
+* Supplemental information for Emacs Developers.
-** Mandatory reading:
+An "Emacs Developer" is someone who contributes a lot of code or
+documentation to the Emacs repository.
-The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
+** Write access to the Emacs repository.
-** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
-included in 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.
-** Remove all trailing whitespace in all source and text files.
+** Using the Emacs repository
-** Use ?\s instead of ? in Lisp code for a space character.
+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.
-* Supplemental information for Emacs Developers.
+Alternately, see admin/notes/git-workflow.
-** Write access to the Emacs repository.
+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.
-Once you become a frequent contributor to Emacs, we can consider
-giving you write access to the version-control repository.
+** Changelog notes
+
+- 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.)
+
+- 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.
+
+- 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.
+
+- In ChangeLog files, 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 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.
+
+** 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. This freeze is announced on the
+emacs-devel mailing list, and not anywhere else.
+
+For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for
+23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x.
+
+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.
+
+The exception is, if you know that the change will be difficult to
+merge to the trunk (eg because the trunk code has changed a lot). In
+that case, it's helpful if 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:". This is helpful for the person merging the release
+branch to the trunk (it is handled automatically by gitmerge.el).
+
+
+** Other process information
+See all the files in admin/notes/* . In particular, see
+admin/notes/newfile, see admin/notes/repo.
** Emacs Mailing lists.
** Document your changes.
-Any change that matters to end-users should have a NEWS entry.
+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
+++ /dev/null
-HOW TO COMMIT CHANGES TO EMACS
-
-Most of these points are from:
-
-http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html
-From: Miles Bader
-Subject: commit style redux
-Date: Tue, 31 Mar 2009 12:21:20 +0900
-
-(0) Each commit should correspond to a single change (whether spread
- over multiple files or not). Do not mix different changes in the
- same commit (eg adding a feature in one file, fixing a bug in
- another should be two commits, not one).
-
-(1) Commit all changed files at once with a single log message (which
- in CVS will result in an identical log message for all committed
- files), not one-by-one. This is pretty easy using vc-dir now.
-
-(2) Make the log message describe the entire changeset, perhaps
- including relevant changelog entries (I often don't bother with
- the latter if it's a trivial sort of change).
-
- Many modern source-control systems vaguely distinguish the first
- line of the log message to use as a short summary for abbreviated
- history listing (in arch this was explicitly called the summary,
- but many other systems have a similar concept). So it's nice if
- you can format the log entry like:
-
- SHORTISH ONE-LINE SUMMARY
-
- MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
- CONSISTING OF) CHANGELOG ENTRIES
-
- [Even with CVS this style is useful, because web CVS browsing
- interfaces often include the first N words of the log message of
- the most recent commit as a short "most recent change"
- description.]
-
-(3) Don't phrase log messages assuming the filename is known, because
- in non-file-oriented systems (everything modern other than CVS),
- the log listing tends to be treated as global information, and the
- connection with specific files is less explicit.
-
- For instance, currently I often see log messages like "Regenerate";
- for modern source-control systems with a global log, it's better to
- have something like "Regenerate configure".
-
-(4) (Added in 2014) In commit comments, and ChangeLog files, it is best
- to use ways of identifying revisions that are not dependent on a
- particular version control system. (At time of writing Emacs is
- about to move to its fourth VCS and another move in the future is
- not impossible.) An excellent way to identify commits 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.
-
-Followup discussion:
-http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
-http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html
-
-
-PREVIOUS GUIDELINES FOR CVS
-
-For historical interest only, here is the old-style advice for CVS logs:
-http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
-
-From: Eli Zaretskii
-Subject: Re: Log messages in CVS
-Date: Sat, 29 Dec 2007 16:06:29 +0200
NOTES ON COMMITTING TO EMACS'S REPOSITORY -*- outline -*-
-* Commit metainformation
-
-** Commit in the author's name
-
-If installing changes written by someone else, commit them in their
-name, not yours.
-
-** Commit message format
-
-Commit messages should follow the conventions used in all modern
-distributed version-control systems. That is, they should consist of
-
-- A self-contained topic line, preferably no more than 75 chars long.
-
-- If other content follows the topic line, there should be a blank
- line separating the two.
-
-- Follow the blank line with ChangeLog-like entries for the specific
- changes you made, if any. (As long as Emacs maintains ChangeLog
- files, just copy the entries you made in them to the commit message
- after the blank line.)
-
-- 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.)
-
-- 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.
- http://lists.gnu.org/archive/html/emacs-devel/2014-05/msg00514.html
-
-** Unnecessary metainformation
-
-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.
-
-* Commit to the right branch
-
-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. No new features may be
-added after this point. This is usually some months before the release.
-
-Shortly before the release, a release branch is created, and the
-trunk is then free for development.
-
-For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for
-23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x.
-
-Consult emacs-devel for exactly what kinds of changes are allowed
-on what branch at any time.
-
** elpa
This branch does not contain a copy of Emacs, but of the Emacs Lisp
explanation, and the README file in the branch for usage
instructions.
-* Install changes only on one branch, let them get merged elsewhere if needed.
-
-In particular, install bug-fixes only on the release branch (if there
-is one) and let them get synced to the trunk; do not install them by
-hand on the trunk as well. E.g. if there is an active "emacs-24" branch
-and you have a bug-fix appropriate for the next emacs-24.x release,
-install it only on the emacs-24 branch, not on the trunk as well.
-
-Installing things manually into more than one branch makes merges more
-difficult.
-
-http://lists.gnu.org/archive/html/emacs-devel/2010-03/msg01124.html
-
-The exception is, if you know that the change will be difficult to
-merge to the trunk (eg because the trunk code has changed a lot).
-In that case, it's helpful if you can apply the change to both trunk
-and branch yourself (when committing the branch change, indicate
-in the commit log that it should not be merged to the trunk; see below).
-
* Installing changes from your personal branches.
If your branch has only a single commit, or many different real
If you remove a gnulib module, or if a gnulib module
removes a file, then remove the corresponding files by hand.
-* Backporting a bug-fix from the trunk to a branch (e.g. "emacs-24").
-
-Indicate in the commit log that there is no need to merge the commit
-to the trunk, e.g. start the commit message with "Backport:". This is
-helpful for the person merging the release branch to the trunk.
-
-http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html
-
* How to merge changes from emacs-24 to trunk
[The section on git merge procedure has not yet been written]
projects / emacs.git / commitdiff