[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: generated files in CVS
From:       Nicolas Goutte <nicolasg () snafu ! de>
Date:       2003-09-28 21:10:26
[Download RAW message or body]

On Sunday 28 September 2003 20:18, Mark Bucciarelli wrote:
> On Sunday 28 September 2003 1:52 pm, Nicolas Goutte wrote:
> > On Sunday 28 September 2003 18:46, Mark Bucciarelli wrote:
> > > In the developer guidelines, it says not to put generated files in CVS.
> > > However, I think there should be one exception: the ChangeLog.
> > >
> > > Benefits:
> > >
> > > (1) Helpful to help debug problems with a CVS snapshot or Debian
> > > package (via Orth) when you are not online.
> >
> > Sorry, I cannot follow you.
> >
> > I am trying to imagine to do what I have done yesterday (finding the
> > problem in KZip) by looking at a huge ChangeLog (even if it is only the
> > one of kdelibs/kio/kio.) It is already not always easy to find the right
> > commit in a cvs log, I wonder how you would get it in a big changelog.
>
> You can:
>
> (1) look at recent changes
> (2) search for changes to files you think may be involved
> (3) search for method names you think may be involved
>
> All three can be a big time saver when you are not that familiar with a
> project.  With your KZip stuff, would it have helped to be able to grep the
> log for either (2) or (3)?

Well (2), yes. I knew it was in kzip.cpp (but I had not thought that it was 
months ago.)

>
> > > (2) It might encourage more descriptive CVS comments.
> >
> > I do not think so. People will then make one line comments so that it
> > looks good. People also will stop using CCMAIL because it looks bad (and
> > it would be one place more for spammers to get email addresses.)
>
> I don't follow why this would make comments shorter.  A "good" ChangeLog
> doesn't necessarily mean short comments.

Perhaps I have mixed up with user-visible changelogs, where the text has to be 
small. (See below.)

>
> The script could certainly strip out the CCMAIL info.

In this case, do not forget to catch the bug email addresses to transform them 
in sort of "Bug#12345" or "Closing bug#12345"!

>

> > > (3) It might encourage atomic commits.
> >
> > Personally I would not care, because there is a reason when I do not make
> > atomic commits (mostly to explain exactly the change in the few files of
> > each commit. So we are back at your point 2.)
>
> Ah, you do the opposite of what I was thinking, where someone checks in a
> ton of files, with many changes all mixed together.

Well, yes, mostly I have one task (bug or improvement) done in one commit in a 
few files. Sometimes some of those files are part of a library. It is a case 
where I try to give a specific comment for the library change. (In my case 
for example, I think that the person looking at the log of KWord's export 
filter library is perhaps not interested in knowing for what export filter 
the change was done. He is probably more interested in what the change makes 
for his own export filter.)

>
> > > Negatives:
> > >
(...)
>
> > > Any other negatives?  (This one isn't that bad, as it's still a
> > > negative even if a script isn't used.)
> >
> > - It wastes place on CVS servers, not only in the main server but mainly
> > in the mirrors (including more time needed for users to download or for
> > mirrors to rsync.)
> > - The CVS keyword $Log$ is banned by the commit policies, so why
> > introduce it by a side-way.
> > - Doing constantly cvs log on a CVS server is not without cost.
> > (- any other reason why $Log$ is banned.)
>
> Valid points, all.  Probably the killer ones.  I guess it depends on how
> much you value a good ChangeLog.
>
> I'm just being lazy--I'd rather use good commit comments, then use CVS to
> generate the ChangeLog, rather than try to remember (or reading through the
> cvs log) to make good ChangeLog entries.  Right now, I do neither, because
> I hate entering stuff twice.  :(

Yes, I think that I understand your point of view.

You want a script like:

# %1 is the file with the commit comment.
cat %1 >> Changelog
cvs commit -F %1

>
> Maybe I'll just delete the ChangeLog entirely.  An invalid ChangeLog is
> probably worse that none.
>
> I'll poke around other KDE CVS modules and see how others handle it.

Well, there were two types of changelogs in KDE's sources:
- the detailed one, similar to CVS's log: those have most of the time been 
deleted.
- the user-oriented one: that are those that are still or again in CVS. It is 
user-oriented (compared to the commit comments that are more developer 
oriented.) So you do not put excessive (technical) details and pure technical 
changes are not described. (User comments are like: "monochrome PNG display 
fixed", whereas the commit comment would be more add "use 
QPixmap::convertFromImage with QPixmap::ColorMode to work around Qt bug" and 
with a CCMAIL to close the relevant bug.)

>
> Regards,
>
> Mark

Have a nice day!

>
> >> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to
> >> unsubscribe <<

 
>> Visit http://mail.kde.org/mailman/listinfo/kde-devel#unsub to unsubscribe <<

[prev in list] [next in list] [prev in thread] [next in thread]