Re: ChangeLogs

[Jaroslav Hajek]

On Tue, Jan 6, 2009 at 2:14 PM, John W. Eaton <address@hidden> wrote:
> On  5-Jan-2009, Thorsten Meyer wrote:
>
> | Here is an example of the output of hg log -style ChangeLog for a larger
> | patch:
> | 2008-12-27  Jaroslav Hajek  <address@hidden>
> |
> |         * src/ChangeLog, src/oct-obj.cc, src/oct-obj.h, src/ov-base-diag.cc,
> |         src/ov-base-diag.h, src/ov-base-scalar.cc, src/ov-base.h, src/ov-
> |         bool-mat.cc, src/ov-bool-mat.h, src/ov-bool-sparse.cc, src/ov-bool-
> |         [...]
> |         src/ov-scalar.h, src/ov-str-mat.cc, src/ov-str-mat.h, src/ov.h:
> |         remove valid_as_scalar_index
> |         [f00578b495e9]
>
> Hmm.  It is bad that the default format breaks filenames as that would
> cause trouble for searching.  That should be fixed so that filenames
> are never split.
>
> | Now imagine this patch does 5 different kind of changes in 5 groups of
> | files to accomplish one major change. How should the ChangeLog look in
> | this case?
> | I think, it should still look like a list with 5 items for the 5 groups
> | of files. Is that possible with mercurial? For example, is it possible
> | to define a new style that will output (in ChangeLog format) only the
> | commit message  but not the list of files?
>
> The changelog style for Mercurial is apparently just a template
> definition, so I think that should be possible.  But even so, I don't
> see the problem.  We don't have to write the list of files by hand,
> and in a way it is better than the current hand-edited files because
> it lists all files that were changed (I'll bet we often omit some in
> the hand-edited log entries).
>
> | into the commit message what we used to write into the ChangeLog files
> | preceded by another item, maybe like this:
> |
> | purpose: fix a major bug
> |   * src/file1, src/file2: added this
> |   * scripts/file3, scripts/file4: removed that
> |   * doc/interpreter/file5: updated something else
>
> Yes, to get something that approximates ChangeLogs that follow the GNU
> conventions, we would need to write something like you show.  I would
> do it like this:
>
>  one line summary
>
>  * file1.cc (function): What changed.
>  (other_function): Other change.
>  * file2.cc (function): Another change.
>
> Then it would show up in the generated changelog file as
>
>  2009-01-06  John W. Eaton  <address@hidden>
>
>          * file1.cc, file2.cc:
>          one line summary
>
>          * file1.cc (function): What changed. (other_function): Other change.
>          * file2.cc (function): Another change.
>          [f7a80a86bc8f] [tip]
>
> For me, I think that is close enough if it also simplifies the way we
> work.
>
> The disadvantages I see are that this amount of information can't
> easily be entered at the command line (with hg commit -m "...").  So I
> would probably work like this:
>
>  * make some changes
>
>  * edit a temporary file that has the log message in the format shown
>    above, but without any leading spaces
>
>  * commit the change with "hg commit -l tmp-file"
>

qrefresh supports -e, which launches an editor for the message. import
does not support -e, but I guess I could add it easily.


> Unfortunately, the Emacs ChangeLog mode is not quite the right thing
> for the format of the log message (I would rather not give up M-x
> add-change-log-entry...), but one could just use that then strip out
> the date/user information and the leading whitespace.  It would be easy
> enough to write a simple function to do that, and probably not much
> harder to customize the Emacs ChangeLog mode to make editing these log
> entries easier.  If you are not using Emacs, then I suppose you are
> either already editing ChangeLogs entirely by hand, or you could adapt
> whatever tools your editor has in a similar way.
>
> jwe
>



-- 
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz