Commit messages

[Thomas Doerfler]

Gedare,

I (personally) agree with the summary and outlook you give. I am not
familiar with the existing tooling to generate ChangeLog entries
incrementally. The way such a tool handles branches might be tricky (or
my imagination simply is not good enough).

Discussion might get more practical if an example of an automatically
generated ChangeLog (even a part or some manually generated example)
would be available.

wkr,

Thomas.

Am 31.01.2012 18:59, schrieb Gedare Bloom:
> On Thu, Jan 26, 2012 at 4:51 AM, Thomas Doerfler
> <Thomas.Doerfler at embedded-brains.de> wrote:
>> Sebastian,
>>
>> IMHO the question is not whether a given VCS maintains a ChangeLog
>> internally, the question is more whether the project needs a separate
>> document containing information about the changes.
>>
>> My personal opinion is, that a separate, collected ChangLog is quite
>> useful, even for those users who are not directly working with GIT (e.g.
>> because they just grab the latest tarball).
>>
> Agree, and other reasons such as grepping the source tree. I see some
> advantages to having ChangeLog files separate from git's knowledge,
> and I don't really see any disadvantages (perhaps a small amount of
> lost time, but I think that will be negligible once we have proper
> tools and procedures).
> 
> 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.
> 
> Are there good arguments against automatically generated entries? Ralf
> identified the following:
> * how you want to _replace_ bogus changelog entries,
>  -- Do it manually. Easy if ChangeLogs are generated incrementally.
> Educate developers so they don't push commits that cause bogus
> entries. Use a back-end tool (see below) to avoid human error.
> * how you want to cope handle rtems CVS history.
>  -- Unnecessary if ChangeLog is maintained automatically and
> incrementally from git commit metadata.
> * how you want to handle changelogs of commits the git-commiter
> received from somebody else.
>  -- Use the --author flag of git. git commit --author="Some User
> <someuser at domain>"
> 
> In order to make this work I think we should integrate ChangeLog entry
> generation together with BuildBot or some similar back-end script that
> parses a git push to append ChangeLog entries into the repository
> automatically.
> 
> -Gedare
> 
>> The exact format of the ChangeLog is a different question. As long as
>> GIT is used as the VCS, I tend to let the ChangeLog (at least the
>> entries of the post-CVS era) be generated automatically. I expect to
>> avoid problems with the entry format and make sure that the VCS content
>> and the Changelog content stay in sync.
>>
>> wkr,
>>
>> Thomas.
>>
>>
>> Am 26.01.2012 08:54, schrieb Sebastian Huber:
>>> On 01/24/2012 04:24 PM, Ralf Corsepius wrote:
>>> [...]
>>>> It's quite simple: Automated changelogs are nice in small projects (where
>>>> actually nobody cares about them) but do not meet many larger projects's
>>>> demands and are a true PITA to use.
>>> [...]
>>>
>>> Since the world is great, there are examples for nearly everything.  The
>>> Linux and FreeBSD kernel uses no ChangeLog files at all.  What they
>>> provide are release notes and these are by far more interesting for end
>>> users than a collection of per file changes.
>>>
>>> Using ChangeLog files and Git is absurd.
>>>
>>
>>
>> --
>> --------------------------------------------
>> Embedded Brains GmbH
>> Thomas Doerfler           Obere Lagerstr. 30
>> D-82178 Puchheim          Germany
>> email: Thomas.Doerfler at embedded-brains.de
>> Phone: +49-89-18908079-2
>> Fax:   +49-89-18908079-9
>> _______________________________________________
>> rtems-devel mailing list
>> rtems-devel at rtems.org
>> http://www.rtems.org/mailman/listinfo/rtems-devel


-- 
--------------------------------------------
Embedded Brains GmbH
Thomas Doerfler           Obere Lagerstr. 30
D-82178 Puchheim          Germany
email: Thomas.Doerfler at embedded-brains.de
Phone: +49-89-18908079-2
Fax:   +49-89-18908079-9