Commit messages

[Pavel Pisa]

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.

 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

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/