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.
On Mon, 01 Nov 2010 19:19:41 +0100 Colomban Wendling lists.ban@herbesfolles.org wrote:
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.
[...]
Well. I'll stop here for now, and simply ask the question: "Do we really want to have ChangeLogs in Geany-Plugins' repository?".
For me, a ChangeLog describes what happened, and the VCS messages how exactly it happened. For example, ChangeLog "files: fixed load_vte/vc usage and made vc non-pointer to forbid any vc != NULL checks", while the real changes may consist of three commits, none of which makes it clear why such changes took place. Some people, Adrian for example, prefer to commit in very small portions; an autogenerated ChangeLog of the treebrowser will be quite tedious.
I do agree that lacking a ChangeLog improves the commit messages, but in the above vte/vc example, the goal of the changes would have to be repeated in each message.
Auto generation will work if we approve a policy that only full sets of changes should be commited, so "what happened" equals to "how it happened".
The NEWS file should cover new things, such as "The former hidden preferences can now be edited in Editor -> Preferences -> Various".
In my company, too, the commit messages are not a substitution for the project documentation, which explains what changes were made since the last stable and why.
Am 01.11.2010 21:21, schrieb Dimitar Zhekov:
On Mon, 01 Nov 2010 19:19:41 +0100 Colomban Wendlinglists.ban@herbesfolles.org wrote:
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.
[...]
Well. I'll stop here for now, and simply ask the question: "Do we really want to have ChangeLogs in Geany-Plugins' repository?".
For me, a ChangeLog describes what happened, and the VCS messages how exactly it happened. For example, ChangeLog "files: fixed load_vte/vc usage and made vc non-pointer to forbid any vc != NULL checks", while the real changes may consist of three commits, none of which makes it clear why such changes took place. Some people, Adrian for example, prefer to commit in very small portions; an autogenerated ChangeLog of the treebrowser will be quite tedious.
I would agree if (at least this was the case when I messed with geany-plugins changelogs the last time) the changelog wasn't just the commit messages copy&pasted into it.
But perhaps this changed in the meantime, or is not the case for all plugins so feel free to ignore me :)
Best regards.
Hi,
Le 01/11/2010 21:21, Dimitar Zhekov a écrit :
On Mon, 01 Nov 2010 19:19:41 +0100 Colomban Wendling lists.ban@herbesfolles.org wrote:
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.
[...]
Well. I'll stop here for now, and simply ask the question: "Do we really want to have ChangeLogs in Geany-Plugins' repository?".
For me, a ChangeLog describes what happened, and the VCS messages how exactly it happened. For example, ChangeLog "files: fixed load_vte/vc usage and made vc non-pointer to forbid any vc != NULL checks", while the real changes may consist of three commits, none of which makes it clear why such changes took place.
IMHO your example is not really good since you combine two changes that may have been separated (and you can't really create more than one commit for the second part I'd think), but I understand your point that is basically "ChangeLog != VCS log", right?
I partially agree with this, but I think most "good commits" needs to contain both the intention and the application [1]. IMHO, the VCS log should contain everything I understand you would put in the ChangeLog, and probably a little more. Of course, you will always have commits that don't actually add a feature or fixes a bug (e.g. simply improve the code), but most of the time you will do a change with a good reason (I hope at least! :D), maybe worth mentioning in the ChangeLog.
So am I right that for you the ChangeLog is basically a detailed version of NEWS? If so, why not -- even though then I think the GNU ChangeLog format is probably not the best: what do we care about the date and the file that are affected?
Some people, Adrian for example, prefer to commit in very small portions; an autogenerated ChangeLog of the treebrowser will be quite tedious.
I don't see Adrian's commits as "small", most the contrary BTW :D But same, IMHO needing the commit to "mean" something is basically a good idea.
I do agree that lacking a ChangeLog improves the commit messages, but in the above vte/vc example, the goal of the changes would have to be repeated in each message.
Not sure I agree, since as I understand the example it should have spanned two distinct commits AND ChangeLog entries IMO. But yes, I understand that a part of the VCS history will not really be interesting in the ChangeLog as you describe it.
Auto generation will work if we approve a policy that only full sets of changes should be commited, so "what happened" equals to "how it happened".
...which basically need a DVCS to really be done :D OK, no troll. But again, basically most commit should have a good reason, and not simply be "well, I'm tired, let's commit everything I've done 'til now and go to bed".
But if it would prevent some code fixes to be committed, I don't think it's a good policy.
The NEWS file should cover new things, such as "The former hidden preferences can now be edited in Editor -> Preferences -> Various".
Not exactly I think. IMHO the NEWS file should cover everything that is "worth noting for the daily usage", or "that is relevant for most users". E.g. a summary of the release.
In my company, too, the commit messages are not a substitution for the project documentation, which explains what changes were made since the last stable and why.
Understood, but I think that, even if maybe it cannot be use to auto-generate ChangeLog, the VCS log should contain all these information, but yes, probably also some others.
BTW, perhaps we should then see how everybody sees these different (or not) things that are NEWS, ChangeLog and VCS history.
For example (don't bother Frank, it's not against you :D), with your vision of the ChanegLog, do you think these entries have their place in the ChangeLog?
2010-10-23 Frank Lanitz <frank(at)frank(dot)uvena(dot)de>
- de.po: Minor update of German translation.
2010-10-08 Frank Lanitz <frank(at)frank(dot)uvena(dot)de>
- de.po: Update of German translation.
If I'm from the VCS POV, yes they does; but I'm from the "what changed in this release" POV, the top entry is pointless.
A last question before I take the night as a consultant [2], how do you actually use the ChangeLog, and for what? I think it would help me understand its point :)
Best regards, Colomban
PS: Note that I don't want to raise a conclusion such as "ChangeLogs are evil" or such, I just feel them more annoying than useful nowadays, so I open up the discussion :)
[1] I probably don't make only good commits unfortunately... See Linux kernel's commits for some good examples :p [2] Not sure it's a joke/expression in English...
BTW, perhaps we should then see how everybody sees these different (or not) things that are NEWS, ChangeLog and VCS history.
There are lots of ways to use these files, none is *right* but you need to have a standard :-)
I think that the thread to date has suggested most of the ways they are used, to summarise:
1. The ChangeLog is for non-VCS situations like tarballs. So it should match the VCS commit logs. Generating it automatically or not depends on the process you use to generate the non-VCS situation. If its generated manually (the current Geany process) then keeping it in VCS is good since it maintains the connection between the two.
2. The VCS commit message is to document *why* the commit is made, *what* is changed is recorded by the VCS (much better than we can). Rules on what should be committed are project specific and usually differ depending on if the commit is being made to the trunk, a branch or the developers local private copy where he can commit "This is as far as I got before I went to bed" :-).
3. Changelog and VCS are developer tools, NEWS or Release Notes are user oriented documentation about a release, not every commit.
Release Notes should have *all* changes in user terms, the user should not have to read ChangeLog or VCS to find out what changed in the release since they don't care about what files and functions changed. It should also contain user info such as "this is not backward compatible, you need to change ..." and alternatives to deprecations, stuff not usually included in ChangeLog/VCS commit message.
NEWS IMO should be a summary of major points of the Release notes (eg compatibility breaks) and can also contain non-software related information such as project personnel changes, new websites or whatever and may even contain some future directions.
News and Release Notes probably can't be fully autogenerated from the VCS/ChangeLog, although it can be a start for the Release Notes so no change is forgotten.
Cheers Lex