Re: [Monotone-devel] monotone Hacking

[Stephen Leake]

Richard Levitte <address@hidden> writes:

> In message <address@hidden> on Tue, 11 Sep 2007 07:12:54 -0400, Stephen Leake 
> <address@hidden> said:
>
> stephen_leake> On the other hand, that is the way we typically work. I
> stephen_leake> often notice "little things" while I'm working on one
> stephen_leake> "big thing". Would it be better to _not_ fix them? Or
> stephen_leake> do one commit for each little thing?
> stephen_leake> 
> stephen_leake> Documentation belongs in .texi files, not in commit
> stephen_leake> messages. Commit messages should help you find when a
> stephen_leake> change occured, and give pointers/hints about why, but
> stephen_leake> the real reasons should be in more stable form.
> stephen_leake> 
> stephen_leake> Otherwise, you can get oscillations; "changed to a
> stephen_leake> linked list because it's faster on Windows", "changed
> stephen_leake> to a red-black tree because it's faster on Gentoo"
> stephen_leake> etc. If those comments were in a design file, it would
> stephen_leake> be obvious what's happening. If they are just in the
> stephen_leake> commit messages, it's much harder to notice.
>
> You're talking about two different kinds of documentations.  When I
> update my workspace, or even better, when I'm about to, and I want to
> know what will happen, the most natural is to check out the log.  If
> all the log says is that this and that function was created, this and
> that function was removed, this and that file was renamed to such and
> such, it tells me absolutely NOTHING.

Ok. I hadn't really thought about it from that point of view.

I agree the commit comments should facilitate that task; they should
briefly describe the main point of the changes. Enough so that
someone unfamiliar with the change can decide whether they need to
review the change in more detail or not.

It is difficult to describe how much these messages should say. For
example, I'm tempted to suggest "enough detail to allow someone
unfamiliar with the change to understand what it does". But understand
at what level? From a user's point of view or a maintainer's point of
view?

One problem in this area is merging branches. Typically, the only log
entry is "merged <revid> <revid>". Should the commit message try to
summarize the purpose of the changes in the branch, or should we be
expected to examine the log of the branch? I guess it should not be
hard to give a one or two sentence summary of what the branch was for.

For a concrete example, I'm about to merge nvm.basic_io.inventory. So
the merge commit message could be:

"Change automate inventory output format to use basic_io"

Then for more detail, you can still examine the commit messages for
each change on the branch.

> Documentation in .texi files are fine for user documentation, overall
> architecture, roadmaps, that kind of thing, but to understand what
> individual changes actually do, it suck 747s through a needles head.
> It's simply about traceability.

Right. There are also comments in code for local design decisions.

> As for small changes, I see no problem with them getting in as part of
> something bigger, and being CLEARLY marked as such.  Some might say
> that it's better to try to make them into separate commits, but I
> personally wouldn't care.  If you CAN make them into separate commits,
> then do.

Ok, that's fair. For such small changes, I think the changelog style
(listing each file and function modified) is a good one. Unless it
affects a lot of functions, like a spelling change.

I have wondered about the proper format/content for changes in nvm.
I'd appreciate some written guidance in HACKING.

-- 
-- Stephe