Commit messages

[Gedare Bloom]

On Wed, Feb 22, 2012 at 4:58 AM, Ralf Corsepius
<ralf.corsepius at rtems.org> wrote:
> On 02/21/2012 09:06 PM, Gedare Bloom wrote:
>>
>> On Tue, Feb 21, 2012 at 1:11 PM, Ralf Corsepius
>> <ralf.corsepius at rtems.org>  wrote:
>>>
>>> On 02/21/2012 05:35 PM, Thomas Doerfler wrote:
>>>>
>>>>
>>>> Hi,
>>>>
>>>> just to throw in my two (euro)cents:
>>>>
>>>> Am 21.02.2012 16:53, schrieb Joel Sherrill:
>>>>>
>>>>>
>>>>>
>>>>> But.. we haven't cleaned up from CVS yet.  We are in limbo
>>>>> right now on ChangeLog's and $Id$'s and we need to settle that.
>>>>>
>>>>> + Do we remove $Id$'s?
>>>
>>>
>>> Well, does git have something comparable? CVS's $Id$'s are helpful when
>>> people are referring to files from tarballs, e.g. in bug reports.
>>>
>>>
>> Unless I'm mistaken the "official" tarballs are just the release
>> versions right?
>
> No, ... users may be importing the sources into different VCSes.
>
Got it.

>
>> So I don't see a need to have any redundant versioning
>> information. Maybe I missed something.
>
>
> a) A product's sources must be self contained. It must not have any
> dependency on any vendor infrastructure (such as git), because you can not
> force users to using your infrastructure.
>
> b) This information is only redundant insofar, as it decouples the sources
> from a vendors' infrastructure. This is helpful in longer terms, e.g. when
> this infrastructure gets lost (e.g. when git gets corrupted).
>
A quick google search shows that this $Id$ problem is common and other
projects have had the exact same arguments we are having, and with
good points to be made on both sides. Expanding / embedding file
version information in a file itself is hard to do with git or any
distributed VCS. Partly the problem is that there is not in general an
authoritative central repository, although we are emulating one in our
workflow currently; so in our case we might be able to hack a solution
together with some custom scripts.

It might not be hard to write a script that can be used to generate
file version information (using git) for use by anyone that wants to
create a tarball with versioning information. But I don't think we
need to maintain those versions in the files themselves as they exist
in the repo..

>>>>> + We haven't decided what to do about the ChangeLog files yet. :)
>>>>>    - Do they continue to be maintained or not?
>>>>
>>>>
>>>>
>>>> I would vote YES, but possibly in a different format, if this is
>>>> suitable for the VCS in use.
>>>
>>>
>>> I would vote manually written ChangeLogs in exactly the format we had
>>> used.
>>>
>>>
>> If we do then we should have some good way to update ChangeLog files
>> atomically when pushing changes in order to avoid the potential mess
>> of merging branches--especially long-running development
>> branches--that contain commits that touch ChangeLog files.
>
> Whatfor?
>
> The fundamental problem is whether to use generated ChangeLogs or not.
>
> Like I tried to express before, I am strongly opposed to using generated
> ones, for reasons I am seeming unable to communicate.
>
>
Unless I misunderstood, your main complaint was that automated
ChangeLogs do not work well because they tend to be 1:1 translations
of commit messages.  If we are speaking about the actual merge/push
into the main RTEMS repo, then I don't see why the translation of the
final commit message into a ChangeLog is so bad. We can scrape all the
files that were changed, the author name, and the date to create a
message that (1) adheres to whatever ChangeLog standard we use and (2)
requires zero effort on behalf of the developer other than to provide
a useful commit message when merging a feature branch into RTEMS. If
we settle on a standard for commit messages then this becomes easy.

>>>> Having a detailed history of changes is
>>>> useful in many maintenance cases and we should provide that information
>>>> even for those users working with tarballs instead of direkt GIT access.
>>>
>>>
>>> Exactly. You can not expect users to have git access.
>>>
>>>
>>>>>    - If not, then they need to be renamed. It is confusing to users.
>>>>
>>>>
>>>>
>>>> Archiving the CVS-based Changelogs in place with a suitable name (like
>>>> "Changelog.pre2012") makes sense IMHO.
>>>
>>>
>>> IMO, it does not make sense. We should continue to provide them as
>>> before,
>>> may-be splitting some overly large ones into ChangeLog.<year>  or similar
>>> (This is what GCC does).
>>>
>>>
>> I think it makes sense to rename/archive them as a natural phase of
>> the change to git.
>
> Again, there is nothing natural in what you say.
>
> The rationales to keep Changelogs are independent of the VCS being used.
> It's just that the common git-hype victim fails to understand the reasons.
>
>
Actually the rationale changes, but there still are good reasons to
keep ChangeLogs. The rationale before was so that developers could see
what changed when and by whom. Users typically don't need that
information other than high-level changes / NEWS items. Perhaps RTEMS
users are different owing to the nature of embedded systems
development---certainly those who maintain independent BSPs do need
some extra information regarding what changes in the BSP support
areas.

>> For users trying to find what changed during the
>> 4.11 release cycle, however, it will complicate matters.
>
> I fail to understand this.
>
> We could continue like we did before.
>
>
>>>>>    - If we don't manually maintain them but want to keep them, then an
>>>>>      automated update needs to occur on every commit. Given the
>>>>> ChangeLog's
>>>>>      are scattered through the tree, if we do this, the script will
>>>>> have
>>>>> to update
>>>>>      the appropriate ChangeLogs.
>>>>
>>>>
>>>>
>>>> The current location of ChangeLog files seems quite artifical to me.
>>>
>>>
>>> It isn't artificial.
>>>
>>> Each of these ChangeLogs corresponds to a _subpackage_, which can be
>>> relocated to a different location with fairly small amounts of works.
>>>
>>>
>>>> Ralf's explanation, that they are at the same nodes as the configure.ac
>>>> seems artifical to me either.
>>>
>>>
>>>
>>> Again, no. Each configure.ac makes them a _subpackage_ auto*tool-wise.
>>>
>>> Think about BSPs. Your users will really want a per-BSP ChangeLog and not
>>> a
>>> monolytic toplevel ChangeLog containing all changes of everything.
>>>
>> I think it is a nice idea to consider more arguments than
>> autotool-dependent subpackages: what if autotools goes away, then what
>> is the reasoning behind our placement of ChangeLogs?
>
> Now you are being violent :()
>
I apologize if I came across as being overly aggressive. I am trying
to make a point though that just because something has always been
done one way does not make that the right way to do it.

> The way the autotools are being used is just a reflection of the nature the
> source tree is structurized.
>
> In an ideal world ...
> rm -rf c/src/lib/libbsp/<target>/<bsp>
> ... and the whole BSP is gone without requiring any changes elsewhere, esp.
> without ChangeLogs entries referring to removed code.
>
> We are very close to this.
>
This is a much better argument than before. But I agree with Thomas
that still the choice of these subpackages seems artificial. Also, I
don't see why it matters if the ChangeLog entries refer to removed
code; in fact, I think that when we delete a subpackage we should
still keep its ChangeLog around and indicate in that ChangeLog that we
deleted it (and maybe why)--at least through one release cycle.

>
>> Do we really need
>> ChangeLogs in (just to pick one) ./doc/tools/bmenu/?
>
> Yes. This is an independent package, which actually has nothing to do with
> RTEMS. It is only bundled with RTEMS because nobody but RTEMS uses it.
>
> Ralf
>