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
+If committing changes written by someone else, make the commit 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
-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):
+When a release is prepared, the commit messages are used to generate
+the ChangeLog file. So a typical patch does not touch any of the
+ChangeLog files in the repository, but contains the ChangeLog entries
+in its message. Here is an example commit message (indented):
Deactivate shifted region
Do not silently extend a region that is not highlighted;
- this can happen after a shift.
+ 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.
- Fixes: bug#19003
The general format is as follows.
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.
+ 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".
Copyright-paperwork-exempt: yes
-- If the commit fixes a bug, append a separate line
-
- Fixes: bug#NNNN
-
- where NNNN is the bug number.
+- 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)".
- In ChangeLog entries, there is no standard or recommended way to
identify revisions.
"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.
+- There is no need to mention files such as NEWS, MAINTAINERS, and
+ FOR-RELEASE, or to indicate regeneration of files such as
+ 'configure', in the ChangeLog entry. "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'
+ 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.
+ that do not need separate ChangeLog entries, as well as commits that
+ only modify files that don't need these entries at all.
** Generating ChangeLog entries
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
+ 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.
- Alternatively, you can use the vc-dwim command to maintain commit
messages. When you create a source directory, run the shell command
Please see (info "(elisp)Documentation Tips") or
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
-for more specific tips on Emacs's doc style. Use `checkdoc' to check
+for more specific tips on Emacs's doc style. Use 'checkdoc' to check
for documentation errors before submitting a patch.
** Test your changes.