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