[Geany-devel] Geany-Plugins & ChangeLogs

[Colomban Wendling]

Hi everybody,

While importing a new plugin into Geany-Plugins' autotools build system,
I noticed that having a ChangeLog is mandatory. Since I have some griefs
against version-controlled ChangeLogs, I'll try to expose the problems,
and some possible solutions.

Note that this reflects my point of view, and maybe there is pro and
cons I don't thought about, so take it as-is, and don't hesitate to
prove I'm wrong :)


So, what's the problem? ChangeLogs. They are not a problem by
themselves, but I think they becomes a problem when under version
control (Git, SVN, CVS, Mercurial, Darcs, Bazaar, whatever). We use VCS
for years now, but we still have ChangeLogs. Aren't ChangeLogs a bit
outdated? Are they still useful? Or are they simply a pain from the
past? Before concluding they are, I'll show some arguments against them,
and try to find some for them.


0. Preface

0.1. What are the ChangeLogs for?
ChangeLogs were invented to maintain a list of changes that happened on
something (especially a source code tree, but potentially anything).

0.2. What are VCS for?
VCS were invented to manage an history of changes that happened on
something. They provide logs, and many other useful features.
This seems to overlap with use of ChangeLogs.

1. Problems of ChangeLogs under VCS

1.1. Duplication
Assuming points 0.1 and 0.2, the versioned ChangeLog is a
manually-maintained duplicate of the VCS' history. Moreover, versioning
a file that tracks versions seems a bit pointless, doesn't it?

1.2. Conflicts
ChangeLogs changes at each other change, by definition. So, each VCS
commit stores a new change on that ChangeLog. While this can seem
natural, this likely leads to conflicts when performing merges or
"cherry-picks".

2. Drawbacks of removing ChangeLogs from VCS

2.1. Complete ChangeLog removal
Removing ChangeLog from VCS suggest to remove it completely, even from
traballs where it can be useful [1]. However, it could be auto-generated
from the VCS' history (see 4.1).

3. Advantages of removing ChangeLogs from VCS

3.1. No duplication of the work (see 1.1)

3.2. Less highly-conflicting files (see 1.2)

3.3. (perhaps) Better commit messages
Commiters that don't have to maintain a separate ChangeLog are probably
encouraged to write better commit messages, since it IS the "ChangeLog",
and since they haven't already written the same lines a few minutes
before the commit.

4. Appendix

4.1. ChangeLog generation by VCS
Most VCS have a tool (included or not) that allows to generate standard
ChangeLogs from their history log, which may be used to provide a
ChangeLog in tarballs for example. SVN has svn2cl, Git has git
log-to-changelog, ...


What I suggest is to simply drop ChangeLogs (or at least not make the
mandatory), and if we want them on tarballs, generate them from VCS
history automatically (e.g. on dist-hook).

Well. I'll stop here for now, and simply ask the question: "Do we really
want to have ChangeLogs in Geany-Plugins' repository?".


Regards,
Colomban


[1] Even though I'm not really sure a so detailed log is useful for
somebody that don't use the "trunk" version, NEWS should be enough in
most case, and redirecting to the VCS history may be OK.