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.