[Ffmpeg-devel] Re: [Ffmpeg-cvslog] r8465 - trunk/libavformat/utils.c

[Uoti Urpala]

On Wed, 2007-03-21 at 14:00 +0100, Reimar D?ffinger wrote:
> It makes the log messages longer and harder to skim through when
> searching for something.

I think the best way to deal with this is to include a short summary of
the commit first, then a longer description. If it's hard to describe
the actual change in a few words then just make it a description of the
areas of functionality/code involved. Basically it should be possible to
skip most commits based on the short summary when looking for changes
relevant to some specific problem or feature.

For example my MPlayer commit from a while ago had "Matroska seeking
fixes" as the summary, which should be enough to tell whether it's
interesting when skimming through the log, and then a longer description
of the change.

>  In this case the log message is quite long
> anyway though. Another disadvantage is that you can access the
> information only when you either have email archive or web browser at
> hand, whereas the log information for those of use using git or similar
> is even available when there is no internet at all.
> But most importantly I think sometimes log messages and email thread
> references are misused for things that should actually be documented in
> the code.
> So in short: there are cases where adding such a thread reference
> makes sense, but in most cases IMO it is not necessary (no real
> discussion about the patch) or misplaced (documentation should be in the
> code, not in an email thread) or the essence of the discussion can be
> captured in a two-line log message.

I agree that the information should be primarily either in the commit
message or code comments, and mailing list links present only if the
discussion was especially long/complicated or otherwise hard to
summarize. However I think that keeping commit message lengths down
should not be a priority; it should be enough to make sure you don't
need to read the whole message to know whether it's relevant.