Commit cd2e816c authored by Paul Eggert's avatar Paul Eggert

Lessen focus on ChangeLog files, as opposed to change log entries.

This is in preparation for generating the former automatically
from the latter.
* admin/notes/bugtracker, admin/notes/copyright, admin/notes/newfile:
ChangeLog -> change log
* admin/notes/changelogs: Remove, merging old contents to ...
* admin/notes/repo: ... here.
* doc/emacs/maintaining.texi (Change Log): Mention that ChangeLog files may
be copied to or from a version control system.
* doc/emacs/trouble.texi (Sending Patches): Point to the commit messages.
* doc/lispref/intro.texi (Acknowledgments): ChangeLog file -> change log entries.
* doc/lispref/tips.texi (Library Headers): Emacs uses a version control system.
* etc/CONTRIBUTE: Give advice about git commit messages and how
to generate proposed patches containing them.
parent ff953bc9
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.
......
......@@ -463,10 +463,10 @@ time, rather than by increasing bug number
"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)
......@@ -475,7 +475,7 @@ obvious fix (e.g. a typo), there's no need to clutter the log with the
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
......
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.)
......@@ -22,7 +22,7 @@ author to make a non-trivial total. If so, make sure they have an
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.
......@@ -115,8 +115,8 @@ else it is possible the file should not be in Emacs at all (please
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".
......
......@@ -15,7 +15,7 @@ output under the headings "The following files are not valid DOS file
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.
......@@ -15,6 +22,21 @@ version-control systems. That is, they should consist of
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.
......@@ -112,9 +134,9 @@ http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html
[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
......@@ -166,4 +188,3 @@ again.
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".
......
......@@ -1474,9 +1474,11 @@ different revision with @kbd{C-u C-x v v}.
@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.
......
......@@ -1137,9 +1137,9 @@ new function, all you need to say about it is that it is new. If you
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.
......
......@@ -552,4 +552,4 @@ Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding,
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.
......@@ -1062,9 +1062,9 @@ context.
@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.
......
......@@ -118,13 +118,23 @@ documentation, i.e. Texinfo files.
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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment