Commit messages

[Gedare Bloom]

On Tue, Jan 31, 2012 at 1:27 PM, Thomas Doerfler
<Thomas.Doerfler at embedded-brains.de> wrote:
> 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).
>
I would think that generating the entries during the git push would be
sufficient. If every git commit has the necessary info to create an
entry, then merging will just combine all of those commits, and when
it comes time to git push, the back-end script can make sense of each
commit message and create the ChangeLog entries accordingly. We just
need to hook the right magic into the back-end of git push. (I do not
know how this would be done and am just brainstorming some big picture
ideas. Hopefully someone with know-how is monitoring our discussion.)

> 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