The Hackerlab at regexps.com

Writing Log Entries for Merges

up: arch
next: Arbitrary Patching with delta-patch
prev: Star Topology Branching and Merging

Suppose you have used star-merge or some other commands to merge two or more branches. You are ready to commit those changes, but first you have to write a log message.

All of the changes you've just merged are already explained in existing log messages. Your new log message can simply summarize the changes, and point to the more detailed log entries. arch has commands which help with this.

The command:

        % larch new-on-branch [--reverse] [--dir .] VERSION

reports a list of patches found in a project tree, but not previously merged with VERSION . Those patches are the ones that were added by your merging activity.

You can print a summary of the changes made by those patches by using xargs and the log-ls command. For example, the main development path for arch 1 .0 is called arch--devo--1.0 . I develop new features on various branches. When it comes time to write a log message before committing a merge to arch--devo , I use:

        % larch new-on-branch --reverse arch--devo--1.0 \
          | xargs larch log-ls --full --summary

        lord@regexps.com--2002/arch--lord--1.0--patch-14
            `merge-points' fixes and `new-on-branch' speed-up
        lord@regexps.com--2002/arch--lord--1.0--patch-13
            Use --dir consistently.
        lord@regexps.com--2002/arch--lord--1.0--patch-12
            output format touch-ups

That idiom is captured, along with a little bit of formatting, by the command log-for-merge :

        % larch log-for-merge arch--devo--1.0

        Patches applied:

        * lord@regexps.com--2002/arch--lord--1.0--patch-14
            `merge-points' fixes and `new-on-branch' speed-up

        * lord@regexps.com--2002/arch--lord--1.0--patch-13
            Use --dir consistently.

        * lord@regexps.com--2002/arch--lord--1.0--patch-12
            output format touch-ups

(An advantage of using the formate generated by log-for-merge is that it is understood by other arch commands which automatically format web pages from ChangeLogs .)

That works out nicely as part of a log message if you organize ChangeLogs as I do. In the top-level of the arch source code, I have an automatic ChangeLog for the arch--devo--branch :

        arch/
          arch/ChangeLog

I created that once, using:

        % larch changelog arch--devo--1.0 > ChangeLog

and after that, it is automatically updated with every commit , update , or similar operation.

I also have per-branch ChangeLogs :

    arch/
      arch/ChangeLog.d/
        arch/ChangeLog.d/lord@regexps.com--2002/
          arch/ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord--1.0
          arch/ChangeLog.d/lord@regexps.com--2002/ChangeLog.lord-doc--1.0

Note that lord@regexps.com... is the name of my archive. Two branches that I develop on are:

        arch--lord--1.0
        arch--lord-doc--1.0

and each of those has their own ChangeLog. I created those logs with similar commands. For example:

        % larch changelog arch--lord--1.0 > ChangeLog.lord

To write the log entry for a merge, I start with the output of log-for-merge application shown above, and add a tiny bit of extra text for people browsing the ChangeLogs as plain text:

        Summary: merge with `lord'
        Keywords: 

        Merge with branch `lord'.

        For details, see

            Changelog.d/lord@regexps.com--2002/ChangeLog.lord--1.0

        Patches applied:

        * lord@regexps.com--2002/arch--lord--1.0--patch-14
             `merge-points' fixes and `new-on-branch' speed-up

        * lord@regexps.com--2002/arch--lord--1.0--patch-13
             Use --dir consistently.

        * lord@regexps.com--2002/arch--lord--1.0--patch-12
             output format touch-ups

Note that for each of the Patches applied , there is a corresponding ChangeLog entry in ChangeLog.d .

arch: The arch Revision Control System
The Hackerlab at regexps.com