headers
Colomban Wendling | 1 Nov 2010 19:19
Gravatar

Geany-Plugins & ChangeLogs

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.
(Continue reading)

Permalink | Reply |
headers
Dimitar Zhekov | 1 Nov 2010 21:21
Picon

Re: Geany-Plugins & ChangeLogs

On Mon, 01 Nov 2010 19:19:41 +0100
Colomban Wendling <lists.ban@...> 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
(Continue reading)

Permalink | Reply |
headers
Thomas Martitz | 2 Nov 2010 00:36
Picon
Gravatar

Re: Geany-Plugins & ChangeLogs

Am 01.11.2010 21:21, schrieb Dimitar Zhekov:
> On Mon, 01 Nov 2010 19:19:41 +0100
> Colomban Wendling<lists.ban@...>  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 :)
(Continue reading)

Permalink | Reply |
headers
Colomban Wendling | 2 Nov 2010 03:07
Gravatar

Re: Geany-Plugins & ChangeLogs

Hi,

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

Permalink | Reply |
headers
Lex Trotman | 2 Nov 2010 04:21
Picon

Re: Geany-Plugins & ChangeLogs

>
> 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.
(Continue reading)

Permalink | Reply |

Gmane