Stop updating ChangeLog?

Stop updating ChangeLog?

[Yao Qi]

Hi all,
The discussion in this thread
https://sourceware.org/ml/gdb-patches/2018-02/msg00012.html
leads to a discussion that whether we still need ChangeLog.  I start
a new thread to get more attention on this topic.

In current development, we need to write one ore more changelog
entries for each commit, put them into both git commit log and
ChangeLog files.  How much we can change to existing mode
depends the answers to these following questions,

 #1 Are ChangeLog files useful in GDB releases to various people
 who build GDB releases?
 #2 Are ChangeLog files useful in GDB repo to various GDB
 developers?

a) If answers are Yes/Yes, we keep unchanged,
b) If answers are No/No, we don't need to write changelog entries in
git commit log, nor updating ChangeLog file,
c) If answer are Yes/No, developers still have to write changelog
entries in git commit log, and we can generate ChangeLog on
release from git log.
d) If answers are No/Yes, get use to git to get the information from
git log instead of ChangeLog,

My answers are No/No, so I suggest that we do b).  I can live up with
c), but that needs change in the release process.  What do you think?

-- 
Yao (齐尧)

P.S. I found that this topic has been discussed several times in
various projects (binutils, glibc, etc) without any conclusions.  I do
hope we can make some progress this time :)

Re: Stop updating ChangeLog?

[Simon Marchi]

On 2018-02-05 11:00, Yao Qi wrote:
> Hi all,
> The discussion in this thread
> https://sourceware.org/ml/gdb-patches/2018-02/msg00012.html
> leads to a discussion that whether we still need ChangeLog.  I start
> a new thread to get more attention on this topic.
> 
> In current development, we need to write one ore more changelog
> entries for each commit, put them into both git commit log and
> ChangeLog files.  How much we can change to existing mode
> depends the answers to these following questions,
> 
>  #1 Are ChangeLog files useful in GDB releases to various people
>  who build GDB releases?
>  #2 Are ChangeLog files useful in GDB repo to various GDB
>  developers?
> 
> a) If answers are Yes/Yes, we keep unchanged,
> b) If answers are No/No, we don't need to write changelog entries in
> git commit log, nor updating ChangeLog file,
> c) If answer are Yes/No, developers still have to write changelog
> entries in git commit log, and we can generate ChangeLog on
> release from git log.
> d) If answers are No/Yes, get use to git to get the information from
> git log instead of ChangeLog,
> 
> My answers are No/No, so I suggest that we do b).  I can live up with
> c), but that needs change in the release process.  What do you think?

My answers would be No/No, though I don't build GDB releases from 
tarball, so I can't really tell for #1.

I explained my point of view here: 
https://sourceware.org/ml/gdb-patches/2018-02/msg00036.html

Simon

Re: Stop updating ChangeLog?

[Dmitry Samersoff]

[-- Attachment #1.1: Type: text/plain, Size: 1745 bytes --]

Yao,

> c) If answer are Yes/No, developers still have to write changelog
> entries in git commit log, and we can generate ChangeLog on
> release from git log.

My version.

I use changelog to check what was changed in gdb. I can live with (c)
and get this information directly from git, but it requires some
additional efforts on my side.

-Dmitry

On 02/05/2018 07:00 PM, Yao Qi wrote:
> Hi all,
> The discussion in this thread
> https://sourceware.org/ml/gdb-patches/2018-02/msg00012.html
> leads to a discussion that whether we still need ChangeLog.  I start
> a new thread to get more attention on this topic.
> 
> In current development, we need to write one ore more changelog
> entries for each commit, put them into both git commit log and
> ChangeLog files.  How much we can change to existing mode
> depends the answers to these following questions,
> 
>  #1 Are ChangeLog files useful in GDB releases to various people
>  who build GDB releases?
>  #2 Are ChangeLog files useful in GDB repo to various GDB
>  developers?
> 
> a) If answers are Yes/Yes, we keep unchanged,
> b) If answers are No/No, we don't need to write changelog entries in
> git commit log, nor updating ChangeLog file,
> c) If answer are Yes/No, developers still have to write changelog
> entries in git commit log, and we can generate ChangeLog on
> release from git log.
> d) If answers are No/Yes, get use to git to get the information from
> git log instead of ChangeLog,
> 
> My answers are No/No, so I suggest that we do b).  I can live up with
> c), but that needs change in the release process.  What do you think?
> 


-- 
Dmitry Samersoff
http://devnull.samersoff.net
* There will come soft rains ...


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

Re: Stop updating ChangeLog?

[Joseph Myers]

On Mon, 5 Feb 2018, Yao Qi wrote:

> P.S. I found that this topic has been discussed several times in
> various projects (binutils, glibc, etc) without any conclusions.  I do
> hope we can make some progress this time :)

All those places are the wrong place for actually effecting any change 
other than (c) (generating ChangeLog files at release time having been 
permitted by the GNU Coding Standards for over 20 years).

The correct place for discussion of whether the ChangeLog format is useful 
generically for GNU projects is the bug-standards list, continuing the 
discussion that has been going on intermittently since I started it on 28 
July last year.  If that discussion results in a GCS change along the 
lines I proposed (that is, removing the requirement for ChangeLog format), 
then individual projects can consider what commit log format is most 
useful for them.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Stop updating ChangeLog?

[Yao Qi]

On Mon, Feb 5, 2018 at 7:04 PM, Joseph Myers <joseph@codesourcery.com> wrote:
> On Mon, 5 Feb 2018, Yao Qi wrote:
>
>> P.S. I found that this topic has been discussed several times in
>> various projects (binutils, glibc, etc) without any conclusions.  I do
>> hope we can make some progress this time :)
>
> All those places are the wrong place for actually effecting any change
> other than (c) (generating ChangeLog files at release time having been
> permitted by the GNU Coding Standards for over 20 years).
>
> The correct place for discussion of whether the ChangeLog format is useful
> generically for GNU projects is the bug-standards list, continuing the
> discussion that has been going on intermittently since I started it on 28
> July last year.  If that discussion results in a GCS change along the
> lines I proposed (that is, removing the requirement for ChangeLog format),
> then individual projects can consider what commit log format is most
> useful for them.
>

Joseph,
The format of ChangLog entry is out of the scope of this discussion.
IMO, each project is free to choose whether to write changelog entry
or not (either in commit log or ChangeLog file).  Some GNU projects
have ChangeLog files, some don't.  This discussion is
about how much do we need changelog in GDB.  To me, changelog
are not useful, so the changelog format isn't interesting to me.

-- 
Yao (齐尧)

Re: Stop updating ChangeLog?

[Joseph Myers]

On Mon, 5 Feb 2018, Yao Qi wrote:

> Joseph,
> The format of ChangLog entry is out of the scope of this discussion.
> IMO, each project is free to choose whether to write changelog entry
> or not (either in commit log or ChangeLog file).  Some GNU projects

I don't believe they are so free (yet).  The current (and problematic) GCS 
requirement, that I've been trying to get changed, is for ChangeLog files 
in releases, using a particular format (which I don't think is a good 
format since it forces description at the level of changed to individual 
files and named entities therein, which closely duplicates the information 
in the diffs themselves) - the projects may choose whether that's a 
checked-in file or generated automatically.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Stop updating ChangeLog?

[Joel Brobecker]

> > Joseph,
> > The format of ChangLog entry is out of the scope of this discussion.
> > IMO, each project is free to choose whether to write changelog entry
> > or not (either in commit log or ChangeLog file).  Some GNU projects
> 
> I don't believe they are so free (yet).  The current (and problematic) GCS 
> requirement, that I've been trying to get changed, is for ChangeLog files 
> in releases, using a particular format (which I don't think is a good 
> format since it forces description at the level of changed to individual 
> files and named entities therein, which closely duplicates the information 
> in the diffs themselves) - the projects may choose whether that's a 
> checked-in file or generated automatically.

Joseph is absolutely right, in that, as a GNU project, GDB is
expected to follow the GNU Coding Standards. So we all need to go
and contribute to the dicussion on the bug-standards list.
Let's get rid of the ChangeLog format!

-- 
Joel

Re: Stop updating ChangeLog?

[John Baldwin]

On Monday, February 05, 2018 04:00:36 PM Yao Qi wrote:
> Hi all,
> The discussion in this thread
> https://sourceware.org/ml/gdb-patches/2018-02/msg00012.html
> leads to a discussion that whether we still need ChangeLog.  I start
> a new thread to get more attention on this topic.
> 
> In current development, we need to write one ore more changelog
> entries for each commit, put them into both git commit log and
> ChangeLog files.  How much we can change to existing mode
> depends the answers to these following questions,
> 
>  #1 Are ChangeLog files useful in GDB releases to various people
>  who build GDB releases?
>  #2 Are ChangeLog files useful in GDB repo to various GDB
>  developers?
> 
> a) If answers are Yes/Yes, we keep unchanged,
> b) If answers are No/No, we don't need to write changelog entries in
> git commit log, nor updating ChangeLog file,
> c) If answer are Yes/No, developers still have to write changelog
> entries in git commit log, and we can generate ChangeLog on
> release from git log.
> d) If answers are No/Yes, get use to git to get the information from
> git log instead of ChangeLog,
> 
> My answers are No/No, so I suggest that we do b).  I can live up with
> c), but that needs change in the release process.  What do you think?

I probably have a bit of a biased view as most of my development work is done
without ChangeLogs, so I'm used to just using web interfaces (svnweb, gitweb)
or vc-annotate in Emacs or the like (git log -S is also super helpful) when
examining history.  I also find the contents of a ChangeLog as I currently
understand it to be a description of the diff (but not the "why"), so I find
it to be redundant with 'git diff' rather than providing new information (as
opposed to the "why" we currently include in commit messages).  That probably
puts me in the No/No camp.

c) would save some work on having to always do 'rebase -i' passes to fixup
dates in the ChangeLog files before pushing an approved series.  (I use
git-merge-changelog which at last moves the added entries to the top, but I
still have to go fixup all the dates by hand.)  b) would eliminate a fair bit
of bookkeeping work in my GDB time as Simon has noted.

-- 
John Baldwin

Re: Stop updating ChangeLog?

[Andrew Burgess]

* John Baldwin <jhb@freebsd.org> [2018-02-05 11:07:16 -0800]:

> On Monday, February 05, 2018 04:00:36 PM Yao Qi wrote:
> > Hi all,
> > The discussion in this thread
> > https://sourceware.org/ml/gdb-patches/2018-02/msg00012.html
> > leads to a discussion that whether we still need ChangeLog.  I start
> > a new thread to get more attention on this topic.
> > 
> > In current development, we need to write one ore more changelog
> > entries for each commit, put them into both git commit log and
> > ChangeLog files.  How much we can change to existing mode
> > depends the answers to these following questions,
> > 
> >  #1 Are ChangeLog files useful in GDB releases to various people
> >  who build GDB releases?
> >  #2 Are ChangeLog files useful in GDB repo to various GDB
> >  developers?
> > 
> > a) If answers are Yes/Yes, we keep unchanged,
> > b) If answers are No/No, we don't need to write changelog entries in
> > git commit log, nor updating ChangeLog file,
> > c) If answer are Yes/No, developers still have to write changelog
> > entries in git commit log, and we can generate ChangeLog on
> > release from git log.
> > d) If answers are No/Yes, get use to git to get the information from
> > git log instead of ChangeLog,
> > 
> > My answers are No/No, so I suggest that we do b).  I can live up with
> > c), but that needs change in the release process.  What do you think?
> 
> I probably have a bit of a biased view as most of my development work is done
> without ChangeLogs, so I'm used to just using web interfaces (svnweb, gitweb)
> or vc-annotate in Emacs or the like (git log -S is also super helpful) when
> examining history.  I also find the contents of a ChangeLog as I currently
> understand it to be a description of the diff (but not the "why"), so I find
> it to be redundant with 'git diff' rather than providing new information (as
> opposed to the "why" we currently include in commit messages).  That probably
> puts me in the No/No camp.
> 
> c) would save some work on having to always do 'rebase -i' passes to fixup
> dates in the ChangeLog files before pushing an approved series.  (I use
> git-merge-changelog which at last moves the added entries to the top, but I
> still have to go fixup all the dates by hand.)

You might find this useful:

  https://github.com/T-J-Teru/dotfiles/blob/master/home/bin/git-update-changelogs

Where previously you would do:

  git rebase -i BASE-COMMIT
  # Edit each commit to update the date by hand...

You can now just do:

  git update-changelogs BASE-COMMIT

And you're done.

Enjoy!

Thanks,
Andrew

Re: Stop updating ChangeLog?

[Maciej W. Rozycki]

Hi Yao,

>  #1 Are ChangeLog files useful in GDB releases to various people
>  who build GDB releases?
>  #2 Are ChangeLog files useful in GDB repo to various GDB
>  developers?
> 
> a) If answers are Yes/Yes, we keep unchanged,
> b) If answers are No/No, we don't need to write changelog entries in
> git commit log, nor updating ChangeLog file,
> c) If answer are Yes/No, developers still have to write changelog
> entries in git commit log, and we can generate ChangeLog on
> release from git log.
> d) If answers are No/Yes, get use to git to get the information from
> git log instead of ChangeLog,

 For me it's No/Yes for two reasons:

1. It is often cheaper in terms of computation or I/O to run `grep' on
   local ChangeLog files than on output from `git', which in turn means
   you get results sooner.  I know it's a weak argument, but still.

2. More importantly, many times I found writing a ChangeLog entry the last 
   reflection point when I realised the solution wasn't actually the right 
   one.  This is because at that point you need to give individual changes
   another thought, and then actually look at them from a different angle, 
   to have them properly expressed in ChangeLog-speak.  I expect that at 
   least some people have had a similar experience and I'd like to keep 
   that opportunity.

I reckon we had a discussion before (at the last GNU Tools Cauldron 
perhaps?) where we concluded that we ought to work towards having a GIT 
commit hook extracting embedded ChangeLog entries from the commit 
description and adding them to actual ChangeLog files automagically.  I 
would be in favour to that.  Although myself I have developed a work flow 
which makes pasting ChangeLog entries into files from a commit description 
very little involving, I still find ChangeLog file conflicts a problem 
with backports.

 FWIW,

  Maciej

Re: Stop updating ChangeLog?

[Yao Qi]

"Maciej W. Rozycki" <macro@mips.com> writes:

> 1. It is often cheaper in terms of computation or I/O to run `grep' on
>    local ChangeLog files than on output from `git', which in turn means
>    you get results sooner.  I know it's a weak argument, but still.
>

ChangeLog is a summary of 'git log', it is fast to do search in it, but
the benefit-cost ratio is quite low, IMO.  We have 1979 ChangeLog
entries in 2017, and we must spend some efforts to create these
entries.  Some of them have more than 40 lines, and all of them are not
useful, AFAICS. Most of these long entries just describe some mechanical
changes by "Likewise".

> 2. More importantly, many times I found writing a ChangeLog entry the last 
>    reflection point when I realised the solution wasn't actually the right 
>    one.  This is because at that point you need to give individual changes
>    another thought, and then actually look at them from a different angle, 
>    to have them properly expressed in ChangeLog-speak.  I expect that at 
>    least some people have had a similar experience and I'd like to keep 
>    that opportunity.

Yes, I had the similar experience too.  What we need here is to jump out
of the code/patch, and think about the big picture again.  I did that
by means of writing commit log, and it happens several times that I find
some flaws when I write commit log.  We can still describe the design
and change of patch in commit log, which is more valuable and less
mechanical than ChangeLog.

-- 
Yao (齐尧)