Re: [ft-devel] Re: Git and ChangeLogs

[David Turner]

2009/4/15 Werner LEMBERG <address@hidden>

Please no.  This is even more work.

IMHO we should force everyone to commit *small* chunks, split into
easily readable code fragments.  This would help more than anything
else.

OK, then I think we should definitely make the ChangeLog format easier
to generate and edit in case of conflicts (I don't think it's painless to merge),
which would mean:

- no TABs in the file. Period
- when giving the list of changed files, just use one file per line, without a prefix like "*"
- it's pretty obvious when a line only consists in a file name, and it not a description, so don't indent them specially
- use 4 spaces to indent the file-specific change description.
- except if there is ambiguity (i.e. when a single file was touched for two distinct reasons, something which should be avoided more easily with git than CVS), there is no need to list the functions/types/modified by a change unless it touches the public API.


For example, replace:

2009-03-20  Werner Lemberg  <address@hidden>

    Fix Savannah bug #25923.

    * src/cache/ftccmap.c (FTC_CMAP_HASH): Fix typo.

with:

2009-03-20  Werner Lemberg  <address@hidden>

Fix #25923.

src/cache/ftccmap.c
    Fix typo.

A more complicated example would be to replace:

2009-03-12  Werner Lemberg  <address@hidden>

    Fix some FreeType Coverity issues as reported for Ghostscript.

    * src/base/ftobjs.c (FT_New_Face, FT_New_Memory_Face): Initialize
    `args.stream' (#3874, #3875).
    (open_face_PS_from_sfnt_stream): Improve error management (#3786).
    * src/base/ftmm.c (ft_face_get_mm_service): Fix check of `aservice'
    (#3870).
    * src/base/ftstroke.c (ft_stroke_border_get_counts): Remove dead
    code (#3790).
    * src/base/ftrfork.c (raccess_guess_apple_generic): Check error
    value of `FT_Stream_Skip' (#3784).

    * src/type1/t1gload.c (T1_Load_Glyph): Check `size' before accessing
    it (#3872)

    * src/pcf/pcfdrivr.c (PCF_Glyph_Load): Check `face' before accessing
    it (#3871).
    * src/pcf/pcfread.c (pcf_get_metrics): Handle return value of
    `pcf_get_metric' (#3789, #3782).
    (pcf_get_properties): Use FT_STREAM_SKIP (#3783).

    * src/cache/ftcmanag.c (FTC_Manager_RegisterCache): Fix check of
    `acache' (#3797)

    * src/cff/cffdrivr.c (cff_ps_get_font_info): Fix check of `cff'
    (#3796).
    * src/cff/cffgload.c (cff_decoder_prepare): Check `size' (#3795).
    * src/cff/cffload.c (cff_index_get_pointers): Add comment (#3794).

    * src/bdf/bdflib.c (_bdf_add_property): Check `fp->value.atom'
    (#3793).
    (_bdf_parse_start): Add comment (#3792).

    * src/raster/ftraster.c (Finalize_Profile_Table): Check
    `ras.fProfile' (#3791).

    * src/sfnt/ttsbit.c (Load_SBit_Image): Use FT_STREAM_SKIP (#3785).

    * src/gzip/ftgzip.c (ft_gzip_get_uncompressed_size): Properly ignore
    seek error (#3781).

With:

2009-03-12  Werner Lemberg  <address@hidden>

Fix some FreeType Coverity issues as reported for Ghostscript.

src/base/ftobjs.c
    Initialize `args.stream' (FT_New_Face, FT_New_Memory_Face) (#3874, #3875).
    Improve error management (open_face_PS_from_sfnt_stream) (#3786).

src/base/ftmm.c
    Fix check of `aservice', #3870.

src/base/ftstroke.c
    Remove dead code (#3790).

src/base/ftrfork.c
    Check error value of `FT_Stream_Skip' (#3784).

 src/type1/t1gload.c
    Check `size' before accessing it (#3872)

 src/pcf/pcfdrivr.c
    Check `face' before accessing it (#3871)

src/pcf/pcfread.c
    Handle return value of `pcf_get_metric' (pcf_get_metrics) (#3789, #3782).
    Use FT_STREAM_SKIP (pcf_get_properties) (#3783).

src/cache/ftcmanag.c
    Fix check of `acache' (#3797).

src/cff/cffdrivr.c
    Fix check of `cff' (#3796).

src/cff/cffgload.c
    Check `size' (#3795).

src/cff/cffload.c
    Add comment (#3794).

src/bdf/bdflib.c
    Check `fp->value.atom'  (_bdf_add_property) (#3793).
    Add comment (_bdf_parse_start) (#3792).

src/raster/ftraster.c
    Check `ras.fProfile' (#3791).

src/sfnt/ttsbit.c
    Use FT_STREAM_SKIP (#3785).

src/gzip/ftgzip.c
    Properly ignore seek error (#3781).

One goal of this format is to make it very easy generate from the output of "git diff --name-only" or something similar.

In all cases, editing the current ChangeLog by hand is too tedious. The fact that you spend a non-trivial amount of
your time reformating and complementing it doesn't encourage me, and probably others, to do a better work here too :-)

   Werner