Commit messages
Pavel Pisa
ppisa4lists at pikron.com
Tue Jan 31 19:15:44 UTC 2012
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/
More information about the devel
mailing list