Re: changelog -vv (was Re: TortoiseSVN 1.3.1 released)

Jean-Marc van Leerdam wrote:

> Agreed, but here I think it would be wise to use the same method you
> currently use when replying to the dev list (you know, your trademarked
> 'fixed in revision NNNN' ;)

I wouldn't trademark something like this. I'd rather have as many people
as possible copy/imitate this :)

> That would provide the entry point for users interested enough to start
> digging for details.

But I also like to keep the changelog short. Some bugs I don't even
mention in there, because they're trivial or (if the user ever notices
it) are only annoying.

> Ok then. I hope you like books, because that one will be long:
>
[snip]
>
>
> Steve can you elaborate on this ;-)

That's what I'm always afraid of. If I provide a detailed description
(which is by nature always very technical), then users don't understand
it and ask me to explain it to them.
So I only write stuff like "fixed crash when ..." or "fixed crashes in
the cache".
If a user has experienced crashes, he knows that those might be fixed.
If it still crashes then with the updated version, he knows that there
are still some bugs left. A user doesn't need to know more, and usually
doesn't even care.

> But you did put something like this explanation somewhere in the code
> and/or log messages did you? Because this information IS relevant, if
> not for yourself then at least for the poor soul ;) that has to maintain
> your code in 10 years.

I wrote a log message for the commit (r5464). But not that detailed.
Because this is something more suited for a programming book. Yes, I
admit I didn't know about such problems before, because I never had to
deal with multiple processors and multiple first-level caches. But now
that I do (or better: others do and I receive the crashreports), I've
read up on such issues and learned it.
You don't document how an if/while/... works either.

> Do keep in mind that every program over 200 lines of code ;) will have
> areas that are left alone for long periods of time, and even with one
> developer, that piece of code will look like being written by someone
> else. Without proper comments and version history available, maintenance
> will become harder.

Every programmer knows that. But every programmer also knows that good
documentation and good comments are rare, because you either don't have
the time or you forget the comments or you just think that it's
'obvious' or ...

Stefan

-- 
        ___
   oo  // \\      "De Chelonian Mobile"
  (_,\/ \_/ \     TortoiseSVN
    \ \_/_\_/>    The coolest Interface to (Sub)Version Control
    /_/   \_\     http://tortoisesvn.tigris.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tortoisesvn.tigris.org
For additional commands, e-mail: dev-help@tortoisesvn.tigris.org