[Geany-devel] ChangeLog for Geany: is that useful, for who and how? (was Re: Geany-Plugins: Please check for ChangeLog-entries on commit)

Colomban Wendling lists.ban at xxxxx
Mon Sep 19 15:45:04 UTC 2011


Le 19/09/2011 08:15, Frank Lanitz a écrit :
> Hi folks,
>
> Another episode from topic improving plugins by Frank ;)
>
> In last time I saw a lot of changes going in into plugins without
> having a ChageLog entry set.
>
> Its not always useful in every case but its a nice thing for users of
> trunk and also stable releases to have a middle view between NEWS-file
> which is in most cases only a very short compilation of changes and
> the very, very verbose svn/git log view. So I'm bagging you to have
> in mind updating your ChangeLog and when every updating po-files or
> something else inside geany-plugins/trunk/geany-plugins/po I make it
> mandatory ;)

Oh no, I planned to start (again [1]) a discussion about *removing*
ChangeLog committing :D  (OK, I though about Geany itself, not GP)

I'll start it right now then, if you don't mind.


Introduction
------------

My POV on ChangeLogs is that they are from the old days, the time nobody
used VCS, so it was a VCS log.  Nowadays with VCS, I think a ChangeLog
only causes useless efforts -- especially if combined with a DVCS, with
which you got the full history locally [2].

So, I think we should get rid of a versioned ChangeLog.


What's the ChangeLog's problems?
--------------------------------

Here are a few points (not really sorted) I see against versioned
ChangeLogs, why I don't really like them:

1) They causes VCS conflicts.  When doing a perfectly linear
development, it's not a so big deal -- only two concurrent commits could
require somebody to fix a conflict --, but when merging branches it is
far less straightforward.

2) They needs to be maintained, as Frank just said.  I feel this as a
useless additional effort since we have the VCS commit, moreover since
both will look quite the same in practice.

3) Some people argue that ChangeLogs don't hold all the information a
VCS log would hold, and are less clobbered with uninteresting changes.
While I might agree that a plain VCS log might contain more entries than
a ChangeLog for the same tree, I also think that the ChangeLog is *far*
less useable that the VCS log.
Why?  Because using the VCS, one can filter by directories, files,
commits, branches, etc., many things that are very hard, if not
impossible, to do with a ChangeLog.  So I thing that even if the VCS log
might contain a few uninteresting entries for some ChangeLog readers, it
is so easier to filter the ones to show I don't think it is a real concern.

4) Who actually reads ChangeLog that couldn't do the same with VCS log?
 OK, SVN is a pain to use when it comes to play with the history because
it's laggy, but imagine you were using a DVCS like, say, Git, where
navigating the history is instantaneous.
I mean, who is interested by ChangeLog's content actually?

 4.1) Developers?  I think they better use VCS log, it's more complete
and as I already said, I think it's more flexible (VCS have log, blame,
bisect, show, diff, etc.).
 4.2) Users?  I think either NEWS is complete enough, or ChangeLog is
clobbered with useless information (like date, authors, modified files,
etc.).

5) It's a versioned file that records changes... sounds weird, doesn't it?


What format a ChangeLog should actually have, if any?
-----------------------------------------------------

If it is meant for power users for whom the NEWS is not complete enough
(4.2), I think that we should then just make it a more complete version
of NEWS, e.g. a list of changes but without dates, authors and files
(maybe that's Release Notes?).

It would then either be built like NEWS, e.g. manually soon before
release, or somewhat automated (see below).

However, if we just want ChangeLog to be the VCS history for the non-VCS
situations like tarballs, I think that generating it from VCS log is
good enough.


Could ChangeLog be auto-generated?
----------------------------------

I think the answer is "yes".

If ChangeLog is a VCS log for tarballs, it's very easy to generate it,
many scripts already exists for various VCS (e.g. I know GLib does it,
for a concrete example).


If ChangeLog is a filtered version of the VCS' log (with either format
we want), we could imagine we annotate commits so that we could
automatically filter them for inclusion in the generated ChangeLog.
E.g. in a git-style pseudo-header [3], something like:

  changelog-entry: [true|false]

or something.  If we choose something like this, we probably could even
setup commit hooks to check that the header is present to make sure we
don't forget it by accident.

Such generated ChangeLog might even only contain the commit summary
(e.g. the first line in a good Git-style commit) if we think the whole
message might not be useful.


Conclusion
----------

I know I already started a thread on a very close topic about a year ago
[1], but I think it might be interesting to ask again since we're
supposed to change a little the Geany's commit workflow with a VCS
change, so it's the right time I guess.  And maybe some people have
changed their mind? :D

Honestly the part that really frightens me is the conflicts if we adopt
a merge-based (or any non-linear) workflow.


So, this is it.  I'm waiting for any POVs, remarks, flamewars, insults,
etc. you find appropriate :)

Regards,
Colomban



[1] http://lists.uvena.de/pipermail/geany-devel/2010-November/003401.html
[2] and we're supposed to witch to Git after the release, and it's a DVCS :)
[3] which, like most pseudo-headers like signed-of-by, acked-by, etc are
actually commit's footers...



More information about the Devel mailing list