Re: Status update - version 5.2.2, cvs->git conversion, plans

[Daniel J S. <dan...@ie...>]

On 11/16/2017 03:32 PM, Dima Kogan wrote:
> Daniel J Sebald <dan...@ie...> writes:
> 
>> On 11/16/2017 12:28 PM, Dima Kogan wrote:
>>> Daniel J Sebald <dan...@ie...> writes:
>>>
>>>> On 11/16/2017 12:17 AM, sfeam via gnuplot-beta wrote:
>>>>
>>>> Keep the same format for the git log messages as you've been using for
>>>> the ChangeLog, i.e.,
>>>>
>>>> -> One line of "short-log"
>>>> -> List of files that have changed, just like CVS ChangeLog entries
>>>>
>>>> <snip>
>>>>
>>>> 1) Ask the people submitting patches, via their git tools to include the
>>>> file change info in their log messages
>>>
>>> Please, let's not do that. Version control already has this information,
>>> and asking humans to replicate it is both effortfull and error-prone.
>>> Does 'git log --stat' give you what you want?
>>
>> It doesn't.  Stat tells you what files have changed, but it doesn't
>> indicate why.  As an example, here is what is done for Octave:
>>
>> http://hg.savannah.gnu.org/hgweb/octave/rev/f8c263f961c1
>>
>> Are the main developers going to maintain the ChangeLog-like formatted
>> messages?  (It's up to them, does it help in tracking down where a code
>> change may have happened?  Apparently, as they've been doing just that
>> for quite some time.)  If so, why not ask the contributor to do that
>> work rather than the main developers?
>>
>> And the benefit of asking the contributor to do a more detailed log
>> message is that I believe it makes the code less error-prone, not more.
>> Why?  Because when it comes time to create a commit and I have to write
>> a slightly more detailed log message I'm forced to review my code diffs
>> to describe it, and very often I realize there is a slightly better
>> syntax or there is a comment or debugging line I forgot to remove.
>> Describing/reviewing one's code is like using proof-reading or
>> spell-checking.
> 
> I'm all for detailed log messages, but I feel strongly that requiring
> rigid Changelog-like commit messages is counterproductive. If the patch
> is convoluted-enough such that it requires detailed documentation about
> every modified function, and this documentation doesn't belong in a
> comment for some reason, then sure, put whatever is helpful into the log
> message. I will argue, however, than this case is more an exception than
> the rule.

But if everyone uses their own style of documentation, how are people 
searching log messages (in qgit or whatever) and reading the summaries 
supposed to quickly formulate what has changed and where.  One is 
looking to quickly find the info, not try to figure out everyone's style 
of presenting information, or to go searching every code change. 
Instead it's, "Ah, this looks like the changeset where the bug came in, 
so now I will look more closely at the diff hunks themselves." 
Furthermore, I believe there are editors/pagers that will highlight the 
format that gnuplot has been using because it is rigid and known.


> And I think your linked commit illustrates this point: most of that
> commit message is clearly seen from the content of the diff. And the
> message is intended to help out humans, then it's actually too terse.
> This format somehow ends up being both verbose-enough to be a major
> pain, but terse-enough to be unhelpful.

Other entries aren't as terse and give more insight.  And often some 
files are excluded if it was some insignificant change like a comment or 
typo.


> And as a sporadic contributor to multiple projects, I DREAD those that
> have pointless and rigid style requirements. PLEASE don't throw in
> obstacles for new contributors.

I didn't say if there is a new contributor unfamiliar with the process 
that their changeset file (or even a plain patch file) should be 
completely discarded because s/he didn't follow the rules.  But its 
easier for the person writing the changes to summarize them than to have 
the reviewer do so.  Spending five minutes on a log message is a problem 
after spending two-plus hours on a modification and testing?

Dan