+2014-11-19 Paul Eggert <eggert@cs.ucla.edu>
+
+ Lessen focus on ChangeLog files, as opposed to change log entries.
+ This is in preparation for generating the former automatically
+ from the latter.
+ * notes/bugtracker, notes/copyright, notes/newfile:
+ ChangeLog -> change log
+ * notes/changelogs: Remove, merging old contents to ...
+ * notes/repo: ... here.
+
2014-11-17 Oscar Fuentes <ofv@wanadoo.es>
* admin/CPP-DEFINES: Mention MINGW_W64.
"raw" = ?
-** ChangeLog issues
+** Change log issues
*** When you fix a bug, it can be helpful to put the bug number in the
-ChangeLog entry, for example:
+change log entry, for example:
* foo.el (foofunc): Fix the `foo' case. (Bug#123)
bug number.
Similarly, when you close a bug, it can be helpful to include the
-relevant ChangeLog entry in the message to the bug tracker, so people
+relevant change log entry in the message to the bug tracker, so people
can see exactly what the fix was.
*** bug-reference-mode
+++ /dev/null
-If installing changes written by someone else, make the ChangeLog
-entry in their name, not yours.
-
-
-http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg00793.html
- There is no need to make change log entries for files such as NEWS,
- MAINTAINERS, and FOR-RELEASE.
-"There is no need" means you don't have to, but you can if you want to.
-
-
-http://lists.gnu.org/archive/html/emacs-devel/2006-12/msg01135.html
- There is no need to indicate regeneration of files such as configure
- in ChangeLog.
-
-
-http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00940.html
-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.)
assignment. If adding a whole file adjust the copyright statements in
the file.
-2. When installing code written by someone else, the ChangeLog entry
+2. When installing code written by someone else, the commit
should be in the name of the author of the code, not the person who
installs it. Also use commit's "--author" option.
Do not install any of your own changes in the same commit.
report!).
Note that it seems painfully clear that one cannot rely on commit logs,
-or even ChangeLogs, for older changes. People often installed changes
-from others, without recording the true authorship.
+or even change log entries, for older changes. People often installed
+changes from others, without recording the true authorship.
[For reference, most of these points were established via email with
rms, 2007/1, "Copyright years".
names:" and "The following resolve to the same DOS file names:" should
not include any files that end up in the release tarball.
-** Make the ChangeLog entry in the name of the author(s), not your own name.
+** Commit in the name of the author(s), not your own name.
** If appropriate, check that the file compiles OK and that Emacs
builds fine with it. Address any compilation warnings.
NOTES ON COMMITTING TO EMACS'S REPOSITORY -*- outline -*-
-* Use DVCS commenting conventions
+* Commit metainformation
-Commits should follow the conventions used in all modern distributed
-version-control systems. That is, they should consist of
+** 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.
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.)
+
+** 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.
[The section on git merge procedure has not yet been written]
-Inspect the ChangeLog entries (e.g. in case too many entries have been
+Inspect the change log entries (e.g. in case too many entries have been
included or whitespace between entries needs fixing). If someone made
-multiple ChangeLog entries on different days in the branch, you may
+multiple change log entries on different days in the branch, you may
wish to collapse them all to a single entry for that author in the
trunk (because in the trunk they all appear under the same date).
Obviously, if there are multiple changes to the same file by different
This is a semi-automated way to find the revision that introduced a bug.
Browse `git help bisect' for technical instructions.
-
+2014-11-19 Paul Eggert <eggert@cs.ucla.edu>
+
+ Lessen focus on ChangeLog files, as opposed to change log entries.
+ * maintaining.texi (Change Log): Mention that ChangeLog files may
+ be copied to or from a version control system.
+ * trouble.texi (Sending Patches): Point to the commit messages.
+
2014-11-19 Eli Zaretskii <eliz@gnu.org>
* maintaining.texi (Switching Branches): Mention "C-x v r".
@cindex change log
Many software projects keep a @dfn{change log}. This is a file,
normally named @file{ChangeLog}, containing a chronological record of
-when and how the program was changed. Sometimes, there are several
-change log files, each recording the changes in one directory or
-directory tree.
+when and how the program was changed. Sometimes, these files are
+automatically generated from the change log entries stored in version
+control systems, or are used to generate these change log entries.
+Sometimes, there are several change log files, each recording the
+changes in one directory or directory tree.
@menu
* Change Log Commands:: Commands for editing change log files.
feel that the purpose needs explaining, it probably does---but put the
explanation in comments in the code. It will be more useful there.
-Please read the @file{ChangeLog} files in the @file{src} and
-@file{lisp} directories to see what sorts of information to put in,
-and to learn the style that we use. @xref{Change Log}.
+Please look at the change log entries of recent commits to see what
+sorts of information to put in, and to learn the style that we use.
+@xref{Change Log}.
@item
When you write the fix, keep in mind that we can't install a change that
+2014-11-19 Paul Eggert <eggert@cs.ucla.edu>
+
+ Lessen focus on ChangeLog files, as opposed to change log entries.
+ * intro.texi (Acknowledgments): ChangeLog file -> change log entries.
+ * tips.texi (Library Headers): Emacs uses a version control system.
+
2014-11-09 Glenn Morris <rgm@gnu.org>
* Makefile.in (version): Remove variable.
Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
For a more complete list of contributors, please see the relevant
-ChangeLog file in the Emacs sources.
+change log entries in the Emacs source repository.
@item ;;; Change Log:
This begins an optional log of changes to the file over time. Don't
put too much information in this section---it is better to keep the
-detailed logs in a separate @file{ChangeLog} file (as Emacs does),
-and/or to use a version control system. @samp{History} is an
-alternative to @samp{Change Log}.
+detailed logs in a version control system (as Emacs does) or in a
+separate @file{ChangeLog} file. @samp{History} is an alternative to
+@samp{Change Log}.
@item ;;; Code:
This begins the actual code of the program.
Ref: "Change Log Concepts" node of the GNU Coding Standards Info
Manual, for how to write good log entries.
+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.)
+
** The patch itself.
If you are accessing the Emacs repository, make sure your copy is
-up-to-date (e.g. with `git pull'), then use
+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
-Else, use
- diff -cp OLD NEW
+With no repository, you can use
+ diff -u OLD NEW
** Mail format.
+2014-11-19 Paul Eggert <eggert@cs.ucla.edu>
+
+ Lessen focus on ChangeLog files, as opposed to change log entries.
+ * CONTRIBUTE: Give advice about git commit messages and how
+ to generate proposed patches containing them.
+
2014-11-13 Paul Eggert <eggert@cs.ucla.edu>
Backport fix for minor Bazaar leftovers.
projects / emacs.git / commitdiff