Commit messages

[Gedare Bloom]

Thanks for your insight. We need input like this from experienced git users :)

On Tue, Jan 31, 2012 at 2:15 PM, Pavel Pisa <ppisa4lists at pikron.com> wrote:
> Hello everybody,
>
> I would like to provide my vague two cents.
>
> The first I would like to express my thanks and heppines
> that RTEMS has decided to switch to GIT. I and the most of my
> colleagues consider it as the best option and we are leaving/have
> left all other source code versioning systems. I believe
> the long term perspective worth the effort and initial
> learning curve and problems.
>
> On Tuesday 31 January 2012 18:59:15 Gedare Bloom wrote:
>> IMO ChangeLog entries (in whatever format) should be automatically
>> generated for each git commit from the message (which should include
>> the PR #), author info, commit (push) date, and the set of files that
>> are modified, added, or removed. Maintaining the ChangeLog
>> automatically and incrementally as a text file will make it easy to
>> fix erroneous entries manually, though ideally those are rare.
>
> As for detailed Changelog - I would not suggest to include it in the
> GIT managed tree. There are more reasons against that
>
>  1) commits should be documented well by commit messages. The first
>    line should be summary which is enough for glimpse look over short log.
>    The rest should be descriptive. Unfortunately RTEMS original CVS commit
>    messages have been kept in different format - usability after conversion
>    is much degraded. I have been sad about that when I have done our
>    local RTEMS CVS conversion to GIT some year ago.
>
>  2) the detailed Changelog for tarball release can be generated during
>    release/snapshot process automatically. I agree, that there is problem
>    with correction of commits descriptions in this case.
>
>  3) but main thing to be aware of when the Changelog is in GIT sources tree is
>    consideration of feature branches, distributed development and MERGEs.
>    They are great and allow to speed development, backport fixes to stable
>    releases, focus on one aspect development without fear that code
>    would not be merged into mainline later etc. etc.
>    BUT when each commits adds lines to the central Changelog file then
>    each merge would end in the conflict resolution. This is really boring.
>    My experience is that most merges are clean or automatically resolved
>    normally and kdiff3 or other tool is used in minimum cases. But Changelog
>    would be central Gordian knot which would be solved during each trivial
>    merge. On the other hand, it could have some positive effect to force
>    everybody think about each processed merge. Changelogs in each
>    subsystem/directory are less problematic.
>
Since RTEMS already uses quite a few distributed ChangeLogs it is hard
to say how problematic merging would be, but I do see that some
ChangeLogs would be quite troublesome, e.g. cpukit/ChangeLog.

>  5) GIT helps to establish practice, when there are many small well readable
>    commits. That is quite good for code changes review but for external
>    code users it is usually too much fine-grained
>
> As I look over other projects they have quite often Changelogs or NEWS files
> in the sources. But they do not update it per each commit. They do update
> of it in a separate commit before release or when there is some bigger
> susbsystem change. I think, that this has advantage, that somebody goes
> through automatically generated log before release, separates bugfixes and
> features introduction and does final review to check if some change
> is not correct. The separate commit nature ensures that there is no clash
> with regular development commits etc.
>
> Coarser granularity of such Changelogs is better for users, because they
> are not flooded by sequences of typical development entries
>
>  - cleaning function calling parameters before bug #1234 resolution
>  - the function F moved to separate file
>  - function F called instead of broken hand crafted second copy of F
>  - final bug #1234 resolution
>  - merge branch bug-hunting to mainline
>
> User prefers Changelog line
>
>  * Fixed bugs
>    -  bug #1234 causing FS corruption resolved
>
The fine granularity of commit messages would also by the same
argument make it harder to generate a user-friendly ChangeLog during
release.  So perhaps it is best to scrap ChangeLogs and to impose some
process of adding bug fix and feature improvements to some other
centralized location... For people who want greater detail they can
checkout the git repo I guess.

I'm coming around to the POV that the ChangeLog should be abandoned in
favor of more user-friendly release notes that are maintained either
in the tree or in some well-known location. But we still need to have
some way to avoid making release engineering burdensome. So
developers/committers should be updating such high-level notes
incrementally. Together with good procedures for committing code RTEMS
this should give good balance between what developers need (detailed
histories of what happened to specific files/functions) and what end
users need (what was fixed, added, removed, or significantly altered).

> Best wishes,
>
>                Pavel
> --
>
>                Pavel Pisa
>    e-mail:     pisa at cmp.felk.cvut.cz
>    www:        http://cmp.felk.cvut.cz/~pisa
>    university: http://dce.fel.cvut.cz/
>    company:    http://www.pikron.com/
>