@need 3200

@node Writing Log Entries for Merges
@chapter Writing Log Entries for Merges

@geindex new-on-branch

@geindex log-for-branch



Suppose you have used @code{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.  @code{arch} has
commands which help with this.


The command:

@example
@group
        % larch new-on-branch [--reverse] [--dir .] VERSION
@end group
@group
@end group
@end example

@noindent
reports a list of patches found in a project tree, but not previously
merged with @code{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
@code{xargs} and the @code{log-ls} command.  For example, the main development
path for arch @code{1}.0 is called @code{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 @code{arch--devo}, I use:

@example
@group
        % larch new-on-branch --reverse arch--devo--1.0 \
          | xargs larch log-ls --full --summary
@end group
@group
@end group
@end example
@example
@group
        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
@end group
@group
@end group
@end example

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

@example
@group
        % larch log-for-merge arch--devo--1.0
@end group
@group
@end group
@end example
@example
@group
        Patches applied:
@end group
@group
@end group
@end example
@example
@group
        * lord@@regexps.com--2002/arch--lord--1.0--patch-14
            `merge-points' fixes and `new-on-branch' speed-up
@end group
@group
@end group
@end example
@example
@group
        * lord@@regexps.com--2002/arch--lord--1.0--patch-13
            Use --dir consistently.
@end group
@group
@end group
@end example
@example
@group
        * lord@@regexps.com--2002/arch--lord--1.0--patch-12
            output format touch-ups
@end group
@group
@end group
@end example

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


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

@example
@group
        arch/
          arch/ChangeLog
@end group
@group
@end group
@end example

I created that once, using:

@example
@group
        % larch changelog arch--devo--1.0 > ChangeLog
@end group
@group
@end group
@end example

@noindent
and after that, it is automatically updated with every @code{commit},
@code{update}, or similar operation.


I also have per-branch @code{ChangeLogs}:

@example
@group
    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
@end group
@group
@end group
@end example

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

@example
@group
        arch--lord--1.0
        arch--lord-doc--1.0
@end group
@group
@end group
@end example

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

@example
@group
        % larch changelog arch--lord--1.0 > ChangeLog.lord
@end group
@group
@end group
@end example

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

@example
@group
        Summary: merge with `lord'
        Keywords: 
@end group
@group
@end group
@end example
@example
@group
        Merge with branch `lord'.
@end group
@group
@end group
@end example
@example
@group
        For details, see
@end group
@group
@end group
@end example
@example
@group
            Changelog.d/lord@@regexps.com--2002/ChangeLog.lord--1.0
@end group
@group
@end group
@end example
@example
@group
        Patches applied:
@end group
@group
@end group
@end example
@example
@group
        * lord@@regexps.com--2002/arch--lord--1.0--patch-14
             `merge-points' fixes and `new-on-branch' speed-up
@end group
@group
@end group
@end example
@example
@group
        * lord@@regexps.com--2002/arch--lord--1.0--patch-13
             Use --dir consistently.
@end group
@group
@end group
@end example
@example
@group
        * lord@@regexps.com--2002/arch--lord--1.0--patch-12
             output format touch-ups
@end group
@group
@end group
@end example

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




