and the committer; use the --author option on the commit command to
specify the actual author; the committer defaults to you.
-** commit messages
+** Commit messages
-When using git, commit messages should use ChangeLog format, with the
-following modifications:
+Typically, a patch creates ChangeLog entries by putting them into its
+commit message, not by changing a ChangeLog file. Here is an example
+commit message (indented):
-- Add a single short line explaining the change, then an empty line,
- then unindented ChangeLog entries.
+ Deactivate shifted region
- 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.
+ Do not silently extend a region that is not highlighted;
+ this can happen after a shift.
+ * 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.
+ Fixes: bug#19003
+
+The general format is as follows.
-- 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.
+- Start with a single unindented summary line explaining the change,
+ then 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
the rationale for a change; that can be done in the commit message
between the summary line and the file entries.
-** ChangeLog notes
+- 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.
- Emacs generally follows the GNU coding standards when it comes to
ChangeLogs:
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.
+ * 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.)
-- If the commit fixes a bug, add a separate line
+- If the commit has authors other than yourself, the commit message
+ should contain a separate line 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
- Fixes: bug#NNNN
+- If the commit fixes a bug, append a separate line
+
+ Fixes: bug#NNNN
where NNNN is the bug number.
of files such as 'configure'. "There is no need" means you don't
have to, but you can if you want to.
+- If a commit message's first line starts with "; ", the message is
+ ignored when generating ChangeLog history files via 'make changelog'
+ or via 'make change-history'. You can use "; " for minor commits
+ that do not need separate ChangeLog entries.
+
+** Generating ChangeLog entries
+
+- You can use various Emacs functions to ease the process of writing
+ ChangeLog entries; see (info "(emacs)Change Log Commands") or
+ http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
+
+- If you use Emacs VC, one way to format ChangeLog entries is to create
+ a top-level ChangeLog file, and update it with 'C-x 4 a' file 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.
+
+- 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
Development normally takes places on the trunk.
You can subscribe to the mailing lists, or see the list archives,
by following links from http://savannah.gnu.org/mail/?group=emacs .
+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.
+
** Document your changes.
Any change that matters to end-users should have an entry in etc/NEWS.