[Geany-devel] Geany-Plugins & ChangeLogs

[Colomban Wendling]

Hi,

Le 01/11/2010 21:21, Dimitar Zhekov a écrit :
> On Mon, 01 Nov 2010 19:19:41 +0100
> Colomban Wendling <lists.ban at 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...