kicad-developers team mailing list archive

[Maciej Suminski <maciej.suminski@xxxxxxx>]

Hi Carsten,

On 11/04/2017 08:47 AM, Carsten Schoenert wrote:
> Hello Orson,
> 
> Am 03.11.2017 um 14:08 schrieb Maciej Sumiński:
> ...
>> I think the e-mail subject contains the first line of commit message
>> that explains the changes and most likely is handled correctly by
>> git-am.
> 
> I disagree on that.
> The subject off a commit should briefly describe *what* the commit is
> about, not why. For well known reasons after 10 years of Git and the
> experience of other VCSs in the past the subject of a git commit should
> be even more compacted to about 50 characters than the length of typical
> text files with 72-80 characters. I know there is no *must* to do so,
> but I think there a lot reason to follow that advice.
> 
> https://git-scm.com/docs/git-commit#_discussion
> 
> Given to that hints (even if you need more than 50 characters in that
> first line) it's mostly impossible to describe why the commit was taken.
> 
> There are great diff tools out there, so I will always see *what* is
> changing within the commit but these tools can't say why the author has
> done this nor can explain further details like extra circumstances or
> further needed changes.
> 
> At after about 10 years usage of git on my side i just can say how
> important some basic rules for commit messages are. I've spent a lot of
> hours to collect the reasons for various commits in different projects
> while trying to adopt functionality into older releases of the project
> (it's not always possible to use always the recent releases). Try to
> image you need to fix security functions in other/older releases without
> a good knowledge what the commits are doing you are looking at and if
> you must believe they are sensibly for you, but this needs to be
> checked. To get the needed overview costs you a lot of time then ...
> time you don't have to work on origin of your issue.
> 
> But mostly it's enough you look at your own commits from one year ago
> e.g, do you really understand within seconds what you have done here?
> 
> With the experience of those years I came to the following conclusion
> already some years ago, writing a good commit message costs you about
> 1-3 minutes or up to 10min in case the change is bigger and it's good to
> write some more information into.
> 
> *But!* It's saves a lot of time on the other side while collaborating!
> And a efficient working together make more fun and is gonna more
> motivating me.

Ok, I misunderstood you earlier. I agree that commit messages should be
descriptive, especially if it is hard to tell what a patch does. In
principle, I do not apply changes that I do not understand. It means
that when neither the patch contents neither the commit message is clear
then there is little chance it will become merged.

In this particular case I replied that Marvin's patches contain clear
description in the corresponding message subject field. The changes are
generic and in my opinion do not require more explanations.

>> Personally, I prefer patches sent as attachments as I do not use
>> a client that is compatible with git-am. I also wonder whether git-am
>> chokes on the lines add by launchpad in every message.
> 
> Agreed, that's why I prefer git-send-email for providing patches like
> Marvin has done. Most of the free MTA clients are also able to handle
> the patches correctly, but all users of Outlook etc. are out here of course.
> 
> You may know about Patchwork [1] originally created by Jeremy Kerr?
> 
> It's a Django based WebUI to pick up patches from emails / mailing lists
> with an API to interacting by CLI. You can organize patch contributions,
> create bundles, add states and responsibilities.
> A lot of projects using this helper (most I know around the linux kernel
> development) to not loose any patches while primarily working by email
> together. I always wanted to setup a local instance of patchwork, due
> lack of time and especially not enough knowledge with postfix / exim I
> haven't ever managed that.
> 
> As far I know it was also possible to ask Jeremy to get an instance on
> patchwork.ozlabs.org [2].

I have not known patchwork, thank you for the tip. In the meantime I
have discovered a way to extract patches sent in the message body from
Thunderbird, so for now I do not need any additional tools. I do not say
it would not be helpful to set up a patchwork site though, as I am
afraid many patches have already drowned in the traffic.

Regards,
Orson

> [1] http://jk.ozlabs.org/projects/patchwork/
>     https://github.com/getpatchwork/patchwork
> [2] http://patchwork.ozlabs.org/
>