April 7 cutover for generating ChangeLog automatically

April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

Currently, each Emacs commit typically contains two copies of its ChangeLog 
entries: one copy in the commit message and one copy as an edit to one or more 
ChangeLog files.  The latter copy is largely redundant and complicates merging, 
so as discussed in Bug#19113 on April 7 we plan to revamp the Emacs master 
commit procedure to eliminate the second copy, so that ordinary commits do not 
alter ChangeLog files.  Instead, the ChangeLog file in the Emacs distribution 
will be generated automatically from recent Git commit messages.

You'll still be able to edit ChangeLog history by running 'make change-history' 
and then committing changes to a new top-level file (initially 'ChangeLog.1') 
that contains an editable copy of non-recent Git commit messages.  However, 
commits ordinarily shouldn't change ChangeLog files and this should simplify 
merging.

The suggested format for commit messages will be changed slightly:

  - File names should be relative to the top level, e.g.:

	Deactivate shifted region

	Do not silently extend an unhighlighted region;
	this can happen after a shift.
	* doc/emacs/mark.texi (Shift Selection): Document this.
	* lisp/window.el (handle-select-window):
	* src/frame.c (Fhandle_switch_frame, Fselected_frame):
	Deactivate the mark.
	Fixes: bug#19003

    (The actual commit message should not be indented.)

  - 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

  - If the commit message should not appear in generated ChangeLogs, its first 
line should start with "; ".

With the new approach there are multiple ways to format ChangeLog entries as 
part of the process of creating a commit message:

  - If you use Emacs VC, you can 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.

The above will all be documented in the files CONTRIBUTE (for ordinary commits) 
and admin/notes/repo (for commits that edit ChangeLog history files).

This change will be installed on the master branch.  Other branches can adopt 
this change whenever convenient.  The emacs-24 branch can continue to use the 
old procedure, and changes to ChangeLog files in emacs-24 can be discarded by 
hand when merging to master.

Although this new style of maintenance is common in other GNU projects, Emacs 
has its own special needs and most likely there will be glitches after the 
transition.  We will do our best to straighten out these problems as they occur.

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Tue, 31 Mar 2015 00:53:48 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> as discussed in Bug#19113 on April 7 we plan to revamp the Emacs master 
> commit procedure to eliminate the second copy, so that ordinary commits do not 
> alter ChangeLog files.  Instead, the ChangeLog file in the Emacs distribution 
> will be generated automatically from recent Git commit messages.

Can we please do this on emacs-24 as well?  I think it would be a
nuisance to have a different procedure for each branch.  It might also
make merging from emacs-24 onto master harder.

Thanks.

Re: April 7 cutover for generating ChangeLog automatically

[Stefan Monnier]

> Can we please do this on emacs-24 as well?

I prefer leaving emacs-24 alone.  There's no 24.6 planned so far in any
case, so the branch will only be kept in case we need an urgent new
release, e.g. because of a serious security hole.


        Stefan

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Paul Eggert <eggert@cs.ucla.edu>,  Emacs-devel@gnu.org
> Date: Tue, 31 Mar 2015 08:57:33 -0400
> 
> > Can we please do this on emacs-24 as well?
> 
> I prefer leaving emacs-24 alone.  There's no 24.6 planned so far in any
> case, so the branch will only be kept in case we need an urgent new
> release, e.g. because of a serious security hole.

So you are saying that emacs-24 should be frozen and no commits should
be pushed to it, once 24.5 is released?

If so, is there a way to freeze it on Savannah (i.e. make so any push
there is refused), to make sure no commits get lost that way?

Re: April 7 cutover for generating ChangeLog automatically

[Stefan Monnier]

> So you are saying that emacs-24 should be frozen and no commits should
> be pushed to it, once 24.5 is released?

Pretty much, except for important/urgent bug fixes or obviously
safe fixes.

> If so, is there a way to freeze it on Savannah (i.e. make so any push
> there is refused), to make sure no commits get lost that way?

I don't think so, no,


        Stefan

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: eggert@cs.ucla.edu,  Emacs-devel@gnu.org
> Date: Tue, 31 Mar 2015 16:49:10 -0400
> 
> > So you are saying that emacs-24 should be frozen and no commits should
> > be pushed to it, once 24.5 is released?
> 
> Pretty much, except for important/urgent bug fixes or obviously
> safe fixes.

But this means there's a real possibility that there will be 24.6.
More importantly, it means that we will have to use 2 confusingly
different procedures.  And now I don't understand why not get rid of
ChangeLogs on the branch as well, the changes to do that are in parts
of Emacs that cannot possibly cause any bugs.

Re: April 7 cutover for generating ChangeLog automatically

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 1232 bytes --]

Paul Eggert writes:

> Currently, each Emacs commit typically contains two copies of its ChangeLog 
> entries: one copy in the commit message and one copy as an edit to one or more 
> ChangeLog files.  The latter copy is largely redundant and complicates merging, 
> so as discussed in Bug#19113 on April 7 we plan to revamp the Emacs master 
> commit procedure to eliminate the second copy, so that ordinary commits do not 
> alter ChangeLog files.  Instead, the ChangeLog file in the Emacs distribution 
> will be generated automatically from recent Git commit messages.
>
> You'll still be able to edit ChangeLog history by running 'make change-history' 
> and then committing changes to a new top-level file (initially 'ChangeLog.1') 
> that contains an editable copy of non-recent Git commit messages.  However, 
> commits ordinarily shouldn't change ChangeLog files and this should simplify 
> merging.

Does it mean that the ChangeLog files won't be updated anymore or that
they will be updated only from time to time (like right before a release
or something like that)?

Also, I think that admin/make-tarball.txt will have to be updated.

Cheers,
Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 1259 bytes --]

On 03/31/2015 07:07 AM, Nicolas Petton wrote:
> Does it mean that the ChangeLog files won't be updated anymore or that
> they will be updated only from time to time (like right before a release
> or something like that)?

The latter.  The ChangeLog history files (ChangeLog.1, etc.) will be 
updated only when someone feels like updating them, either by editing 
them manually and committing the changes, or by running 'make 
change-history'.  'make change-history' will prepend copies of recent 
commit messages to ChangeLog.1, thus causing those commit messages to no 
longer be considered "recent".

There will be only one file called 'ChangeLog', at the top level. You 
can generate it automatically from recent commit messages by running 
'make ChangeLog', but intent is that it is an output file and is not 
committed to the repository.  (Unlike 'make change-history', 'make 
ChangeLog' doesn't cause the commits to be considered "recent".)  'make 
dist' uses 'make ChangeLog' to create the ChangeLog file that is put 
into the tarball.

> I think that admin/make-tarball.txt will have to be updated.
Yes, that's part of the patch proposed in Bug#19113.  Please see:

http://bugs.gnu.org/19113#119

I'm attaching the part that updates make-tarball.txt.

[-- Attachment #2: make-tarball.diff --]
[-- Type: text/x-patch, Size: 2147 bytes --]

diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index 8f8b031..2fe3b69 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -31,28 +31,30 @@ General steps (for each step, check for possible errors):
       M-x authors RET
 
     If there is an "*Authors Errors*" buffer, address the issues.
-    If there was a ChangeLog typo, fix it.  If a file was deleted or
-    renamed, consider adding an appropriate entry to authors-ignored-files,
+    If there was a ChangeLog typo, run "make change-history" and then
+    fix ChangeLog.1.  If a file was deleted or renamed, consider
+    adding an appropriate entry to authors-ignored-files,
     authors-valid-file-names, or authors-renamed-files-alist.
 
     If necessary, repeat M-x authors after making those changes.
     Save the "*Authors*" buffer as etc/AUTHORS.
     Check the diff looks reasonable.  Maybe add entries to
     authors-ambiguous-files or authors-aliases, and repeat.
-    Commit any fixes to ChangeLogs or authors.el.
+    Commit any fixes to authors.el.
 
 3.  Set the version number (M-x load-file RET admin/admin.el RET, then
     M-x set-version RET).  For a release, add released ChangeLog
-    entries (M-x add-release-logs RET).
+    entries (create a ChangeLog symlink a la vc-dwim, then run M-x
+    add-release-logs RET, then run the shell command 'vc-dwim --commit').
 
     For a pretest, start at version .90.  After .99, use .990 (so that
     it sorts).
 
     The final pretest should be a release candidate.  Set the version
     number to that of the actual release.  Pick a date about a week
-    from now when you intend to make the release.  Use M-x add-release-logs
-    to add the ChangeLog entries for that date to the tar file (but
-    not yet to the repository).  Name the tar file as
+    from now when you intend to make the release.  Use vc-dwim and
+    M-x add-release-logs as described above to add the ChangeLog
+    entries for that date to the tar file.  Name the tar file as
     emacs-XX.Y-rc1.tar.  If all goes well in the following week, you
     can simply rename the file and use it for the actual release.
 

Re: April 7 cutover for generating ChangeLog automatically

[nicolas.petton]

[-- Attachment #1: Type: text/plain, Size: 651 bytes --]


Paul Eggert writes:
> I'm attaching the part that updates make-tarball.txt.
>
>  3.  Set the version number (M-x load-file RET admin/admin.el RET, then
>     M-x set-version RET).  For a release, add released ChangeLog
> -    entries (M-x add-release-logs RET).
> +    entries (create a ChangeLog symlink a la vc-dwim, then run M-x
> +    add-release-logs RET, then run the shell command 'vc-dwim
>     --commit').

I don't understand this part, what does "create a ChangeLog symlink a la
vc-dwim" mean? And what does `vc-dwim --commit' does? I have never used
this tool.

Cheers,
Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 454 bytes --]

nicolas.petton@foretagsplatsen.se wrote:
> what does "create a ChangeLog symlink a la
> vc-dwim" mean? And what does `vc-dwim --commit' does?

If you have vc-dwim installed, 'vc-dwim --help' should explain both points. 
I've attached its output.  For the first question, please see the last paragraph 
of the DESCRIPTION, and the EXAMPLE.  For the second question, please see the 
first two paragraphs of DESCRIPTION, and the first option under OPTIONS.

[-- Attachment #2: vc-dwim-help.txt --]
[-- Type: text/plain, Size: 4025 bytes --]

NAME
    vc-dwim - use new ChangeLog entries to direct and cross-check a
    version-control "diff" or "commit" command

SYNOPSIS
    vc-dwim [OPTIONS] [CHANGELOG_FILE...]

    vc-dwim [OPTIONS] --commit CHANGELOG_FILE...

    vc-dwim [OPTIONS] --diff [FILE...]

    vc-dwim [OPTIONS] --print-vc-list

DESCRIPTION
    By default, each command line argument should be a locally modified,
    version-controlled ChangeLog file.  If there is no command line argument,
    vc-dwim tries to use the ChangeLog file in the current directory.  In this
    default mode, vc-dwim works by first computing diffs of those files and
    parsing the diff output to determine which named files are being changed. 
    Then, it diffs the affected files and prints the resulting output.  One
    advantage of using this tool is that before printing any diffs, it warns
    you if it sees that a ChangeLog or an affected file has unsaved changes. 
    It detects that by searching for an editor temporary file corresponding to
    each affected file.  Another common error you can avoid with this tool is
    the one where you create a new file, add its name to Makefiles, etc.,
    mention the addition in ChangeLog, but forget to e.g., "git add" (or "hg
    add", etc.) the file to the version control system.  vc-dwim detects this
    discrepancy and fails with a diagnostic explaining the probable situation.
    You might also have simply mistyped the file name in the ChangeLog.

    Once you are happy with your ChangeLog-derived diffs, you can commit those
    changes and the ChangeLog simply by rerunning the command with the
    --commit option.

    But what if you'd like to use vc-dwim on a project that doesn't have or
    want a ChangeLog file?  In that case, you can maintain your own, private,
    version-controlled ChangeLog file in a different hierarchy.  Then just
    make a symlink to it from the top level directory of the hierarchy in
    which you'd like to use it and everything should work.  Your private
    ChangeLog file need not even use the same version control system as the
    rest of the project hierarchy.

OPTIONS
    --commit
        perform the commit, too

    --author="User Name <user@example.org>"
        Specify the user name and email address of the author of this change
        set.

    --diff
        Determine which version control system manages the first FILE, then
        use that to print diffs of the named FILEs.  If no FILE is specified,
        print all diffs for the current hierarchy.

    --print-vc-list
        Print the list of recognized version control names, then exit.

    --help
        Display this help and exit.

    --version
        Output version information and exit.

    --verbose
        Generate verbose output.

    --debug
        Generate debug output.

EXAMPLE
    Here's how to use vc-dwim in a project that does not version-control a
    ChangeLog file.  Create a repository just for your personal ChangeLog file
    and make a symlink to it from the top-level directory of the project.  For
    projects that use git, I put this tiny auxiliary repository in a directory
    named .git/c.  You can use this bash/zsh alias to set it up and to create
    the symlink:

        git-changelog-symlink-init()
        {
            local d=.git/c
            test -d .git || return 1
            mkdir $d
            touch $d/ChangeLog
            (cd $d && git init && git add ChangeLog && git commit -m. -a)
            ln --backup -s $d/ChangeLog .
        }

RESTRICTIONS
    This tool can be useful to you only if you use a version control system. 
    It's most useful if you maintain a ChangeLog file and create a log entry
    per file per "commit" operation.

    Relies on fairly strict adherence to recommended ChangeLog syntax. 
    Detects editor temporaries created by Emacs and Vim.  Eventually, it will
    detect temporaries created by other editors.

AUTHOR
    Jim Meyering <jim@meyering.net>

    Report bugs to <bug-vc-dwim@gnu.org>.

Re: April 7 cutover for generating ChangeLog automatically

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 651 bytes --]


Paul Eggert writes:
> I'm attaching the part that updates make-tarball.txt.
>
>  3.  Set the version number (M-x load-file RET admin/admin.el RET, then
>     M-x set-version RET).  For a release, add released ChangeLog
> -    entries (M-x add-release-logs RET).
> +    entries (create a ChangeLog symlink a la vc-dwim, then run M-x
> +    add-release-logs RET, then run the shell command 'vc-dwim
>     --commit').

I don't understand this part, what does "create a ChangeLog symlink a la
vc-dwim" mean? And what does `vc-dwim --commit' does? I have never used
this tool.

Cheers,
Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 03/31/2015 10:53 AM, Paul Eggert wrote:

>      Co-authored-by: Joe Schmoe <j.schmoe@example.org>

>      Copyright-paperwork-exempt: yes

In vc-log-edit, will those be entered at the top of the buffer, as 
header fields?

Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

On 03/31/2015 07:45 AM, Dmitry Gutov wrote:
> On 03/31/2015 10:53 AM, Paul Eggert wrote:
>
>> Co-authored-by: Joe Schmoe <j.schmoe@example.org>
>
>> Copyright-paperwork-exempt: yes
>
> In vc-log-edit, will those be entered at the top of the buffer, as 
> header fields? 

That will work, yes.  It will also work if the lines are entered at the 
end of the commit message, or anywhere else in the commit message.

Re: April 7 cutover for generating ChangeLog automatically

[Stefan Monnier]

>  - 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>

Can't we just use "Author: Joe <joe>, Jane <jane>" ?

>  - 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

How are we supposed to remember this one (and make sure it's typed
correctly)?
Could we use "Author: Joe <joe> (tiny change)"?


        Stefan

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 03/31/2015 11:52 PM, Stefan Monnier wrote:

> Can't we just use "Author: Joe <joe>, Jane <jane>" ?

In my experiment, Git seems to ignore everything that comes after the 
first '>' in the "--author" argument. E.g. subsequent 'git show HEAD' 
only shows the first author.

Aside from Co-authored-by, AlsoBy (or Also-By) seems to be the main 
alternative: https://bugs.eclipse.org/bugs/show_bug.cgi?id=375536

Re: April 7 cutover for generating ChangeLog automatically

[Stefan Monnier]

>> Can't we just use "Author: Joe <joe>, Jane <jane>" ?
> In my experiment, Git seems to ignore everything that comes after the first
> '>' in the "--author" argument. E.g. subsequent 'git show HEAD' only shows
> the first author.

We could make vc-git treat

   Author: Joe <joe>, Jane <jane>

as a shorthand for

   Author: Joe <joe>
   Also-By: Jane <jane>

Or something like that,


        Stefan

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 04/01/2015 05:21 AM, Stefan Monnier wrote:

> We could make vc-git treat
>
>     Author: Joe <joe>, Jane <jane>
>
> as a shorthand for
>
>     Author: Joe <joe>
>     Also-By: Jane <jane>
>
> Or something like that,

And handle it automatically in log-edit-extract-headers? That should 
work. We'll also need to somehow prohibit values like:

   Author: Joe <joe>, Jane <jane> (tiny change)

because there's no way to count Jane's lines there.

Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

Stefan Monnier wrote:
>>   - 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>
> Can't we just use "Author: Joe <joe>, Jane <jane>" ?
>
>> >  - 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
> How are we supposed to remember this one (and make sure it's typed
> correctly)?
> Could we use "Author: Joe <joe> (tiny change)"?

I don't see why not.  I suppose someone could modify the 
build-aux/gitlog-to-changelog script to do both things.  That script is copied 
from Gnulib -- I didn't change it.  I'll CC: this to Jim Meyering (who wrote 
that script) to see what he thinks about the suggestion.

Jim, the context is that we're converting Emacs to generate ChangeLog files 
automatically, like coreutils etc. do.  Please see this thread:

http://lists.gnu.org/archive/html/emacs-devel/2015-03/msg01045.html

Emacs master ChangeLog files now generated automatically

[Paul Eggert]

I installed the recently-discussed procedure for generating ChangeLog files 
automatically from commit messages.  When you do a 'git pull' next, expect to 
see many ChangeLog files renamed to ChangeLog.12 or whatever.  From now on, 
ordinary commits should not need to edit ChangeLog files; instead, they should 
merely have commit messages that look like entries in a top-level ChangeLog file 
(a file that is generated automatically, and is not stored in the repository).

I installed this change on Emacs's master branch; other branches can incorporate 
the change as needed.

For more, please see the file 'CONTRIBUTING' on the master branch, or see 
Bug#19113, or see my week-ago email on the topic, here:

https://lists.gnu.org/archive/html/emacs-devel/2015-03/msg01045.html

Re: Emacs master ChangeLog files now generated automatically

[John Wiegley]

>>>>> Paul Eggert <eggert@cs.ucla.edu> writes:

> I installed the recently-discussed procedure for generating ChangeLog files
> automatically from commit messages.

You are officially my hero for today. :)

John

Re: Emacs master ChangeLog files now generated automatically

[Karl Fogel]

"John Wiegley" <johnw@newartisans.com> writes:
>>>>>> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> I installed the recently-discussed procedure for generating ChangeLog files
>> automatically from commit messages.
>
>You are officially my hero for today. :)

Mine too!

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

Hi Paul,

On 03/31/2015 10:53 AM, Paul Eggert wrote:

> The suggested format for commit messages will be changed slightly:
>
>   - File names should be relative to the top level, e.g.:

Shouldn't this rule be accompanied with a change in 
`add-change-log-entry'? Or `find-change-log'?

Re: April 7 cutover for generating ChangeLog automatically

[João Távora]

On Tue, Apr 7, 2015 at 2:24 PM, Dmitry Gutov <dgutov@yandex.ru> wrote:
> Hi Paul,
>
> On 03/31/2015 10:53 AM, Paul Eggert wrote:
>
>> The suggested format for commit messages will be changed slightly:
>>
>>   - File names should be relative to the top level, e.g.:
>
>
> Shouldn't this rule be accompanied with a change in `add-change-log-entry'?
> Or `find-change-log'?

FWIW, If you have the multiple dummy ChangeLog buffers, I think eventually
`log-edit-insert-changelog' does the right thing and inserts the top-level path.

Would be nice to automatically cleanup those buffers though, or not
need  them at all.

-- 
João Távora

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Tue, 7 Apr 2015 15:05:47 +0100
> Cc: Paul Eggert <eggert@cs.ucla.edu>, Emacs Development <Emacs-devel@gnu.org>
> 
> On Tue, Apr 7, 2015 at 2:24 PM, Dmitry Gutov <dgutov@yandex.ru> wrote:
> > Hi Paul,
> >
> > On 03/31/2015 10:53 AM, Paul Eggert wrote:
> >
> >> The suggested format for commit messages will be changed slightly:
> >>
> >>   - File names should be relative to the top level, e.g.:
> >
> >
> > Shouldn't this rule be accompanied with a change in `add-change-log-entry'?
> > Or `find-change-log'?
> 
> FWIW, If you have the multiple dummy ChangeLog buffers, I think eventually
> `log-edit-insert-changelog' does the right thing and inserts the top-level path.
> 
> Would be nice to automatically cleanup those buffers though, or not
> need  them at all.

Create a top-level ChangeLog file with a single dummy entry, and the
next add-change-log-entry will automatically find that ChangeLog and
format the entry as required.

Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

Eli Zaretskii wrote:
> Create a top-level ChangeLog file with a single dummy entry, and the
> next add-change-log-entry will automatically find that ChangeLog and
> format the entry as required.

Yes, that's what I typically do.  vc-dwim encourages this style; with it, the 
top level ChangeLog is a symlink to somewhere else, which has other advantages.

Another hack would be something like this:

(setq change-log-default-name "/home/eggert/src/gnu/emacs/master/ChangeLog")

Though of course this won't work well if you have the habit of working on 
multiple projects or repositories.

I expect add-change-log-entry could be made smarter, so that it would do the 
right thing with a vanilla copy of Emacs checked out from the repository, one 
that doesn't have a ChangeLog file.

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 04/07/2015 05:27 PM, Eli Zaretskii wrote:

 > Create a top-level ChangeLog file with a single dummy entry, and the
> next add-change-log-entry will automatically find that ChangeLog and
> format the entry as required.

Nice hack. But won't this leave a lot of unneeded code in add-log.el?

If we're not going to change it, should we have some setting in the 
top-level .dir-locals.el that will force the proper ChangeLog location 
automatically?

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Tue, 07 Apr 2015 20:25:37 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: eggert@cs.ucla.edu, Emacs-devel@gnu.org
> 
> On 04/07/2015 05:27 PM, Eli Zaretskii wrote:
> 
>  > Create a top-level ChangeLog file with a single dummy entry, and the
> > next add-change-log-entry will automatically find that ChangeLog and
> > format the entry as required.
> 
> Nice hack. But won't this leave a lot of unneeded code in add-log.el?

add-log.el is not only for Emacs.  Or maybe I don't understand which
unneeded code did you have in mind.

> If we're not going to change it, should we have some setting in the 
> top-level .dir-locals.el that will force the proper ChangeLog location 
> automatically?

I don't see why not.

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 04/07/2015 08:32 PM, Eli Zaretskii wrote:

> add-log.el is not only for Emacs.

Then it's probably fine.

>> If we're not going to change it, should we have some setting in the
>> top-level .dir-locals.el that will force the proper ChangeLog location
>> automatically?
>
> I don't see why not.

Is there an existing var like that? Or do you see a good place to stick 
a new one?

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Tue, 07 Apr 2015 21:16:37 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: joaotavora@gmail.com, eggert@cs.ucla.edu, Emacs-devel@gnu.org
> 
> >> If we're not going to change it, should we have some setting in the
> >> top-level .dir-locals.el that will force the proper ChangeLog location
> >> automatically?
> >
> > I don't see why not.
> 
> Is there an existing var like that?

change-log-default-name?

Re: April 7 cutover for generating ChangeLog automatically

[Paul Eggert]

On 04/07/2015 11:27 AM, Eli Zaretskii wrote:
> change-log-default-name? 

I expect a relative file name there will be interpreted relative to the 
directory containing the source file which is not what we want, and an 
absolute file name would work only if everybody puts their source 
directory at the same localtion ("/home/rms/src/emacs/master", say).

We could establish an extended interpretation for that variable, e.g., 
"./ChangeLog" would be relative to the directory containing the 
.dir-locals.el file, but I assume that'd require a change to the code.

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Tue, 07 Apr 2015 13:09:22 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: joaotavora@gmail.com, Emacs-devel@gnu.org
> 
> On 04/07/2015 11:27 AM, Eli Zaretskii wrote:
> > change-log-default-name? 
> 
> I expect a relative file name there will be interpreted relative to the 
> directory containing the source file which is not what we want, and an 
> absolute file name would work only if everybody puts their source 
> directory at the same localtion ("/home/rms/src/emacs/master", say).
> 
> We could establish an extended interpretation for that variable, e.g., 
> "./ChangeLog" would be relative to the directory containing the 
> .dir-locals.el file, but I assume that'd require a change to the code.

Or maybe the value of change-log-default-name could be an expression
to be evaluated, in which case we could use in that expression
locate-dominating-file whose arguments are "." and ".git".

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 04/08/2015 08:36 AM, Eli Zaretskii wrote:

> Or maybe the value of change-log-default-name could be an expression
> to be evaluated, in which case we could use in that expression
> locate-dominating-file whose arguments are "." and ".git".

Won't that clash with file-local vars' security?

Either every user trying to edit a file inside Emacs tree will have to 
explicitly allow this expression to be evaluated, or, if we somehow 
silently eval it, in a different project it could do something unwanted 
without the user's knowledge.

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Wed, 08 Apr 2015 18:07:54 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: joaotavora@gmail.com, Emacs-devel@gnu.org
> 
> On 04/08/2015 08:36 AM, Eli Zaretskii wrote:
> 
> > Or maybe the value of change-log-default-name could be an expression
> > to be evaluated, in which case we could use in that expression
> > locate-dominating-file whose arguments are "." and ".git".
> 
> Won't that clash with file-local vars' security?

How can calling locate-dominating-file be insecure?

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 04/08/2015 06:18 PM, Eli Zaretskii wrote:

> How can calling locate-dominating-file be insecure?

How will we check that the expression only calls 
`locate-dominating-file'? And will it be prohibited from calling 
anything else?

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Wed, 08 Apr 2015 18:31:22 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: eggert@cs.ucla.edu, joaotavora@gmail.com, Emacs-devel@gnu.org
> 
> On 04/08/2015 06:18 PM, Eli Zaretskii wrote:
> 
> > How can calling locate-dominating-file be insecure?
> 
> How will we check that the expression only calls 
> `locate-dominating-file'?

I have no idea.

> And will it be prohibited from calling anything else?

If needed, yes.

Re: April 7 cutover for generating ChangeLog automatically

[Eli Zaretskii]

> Date: Wed, 08 Apr 2015 18:37:44 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: eggert@cs.ucla.edu, joaotavora@gmail.com, Emacs-devel@gnu.org
> 
> > Date: Wed, 08 Apr 2015 18:31:22 +0300
> > From: Dmitry Gutov <dgutov@yandex.ru>
> > CC: eggert@cs.ucla.edu, joaotavora@gmail.com, Emacs-devel@gnu.org
> > 
> > On 04/08/2015 06:18 PM, Eli Zaretskii wrote:
> > 
> > > How can calling locate-dominating-file be insecure?
> > 
> > How will we check that the expression only calls 
> > `locate-dominating-file'?
> 
> I have no idea.

How about a special value of change-log-default-name, which will cause
find-change-log to call locate-dominating-file?

Re: April 7 cutover for generating ChangeLog automatically

[Stefan Monnier]

> How about a special value of change-log-default-name, which will cause
> find-change-log to call locate-dominating-file?

Personally, I just did "touch ChangeLog" once (per Git workdir) and
moved on.


        Stefan

Re: April 7 cutover for generating ChangeLog automatically

[Dmitry Gutov]

On 04/08/2015 10:15 PM, Stefan Monnier wrote:

> Personally, I just did "touch ChangeLog" once (per Git workdir) and
> moved on.

Well, ok (works for me too, yay). I've added a small change to 
CONTRIBUTE, that probably would've made this course of action clearer to me.