[yocto] [oe] [OE-core] Git commit process question.

[Paul Eggleton]

On Thursday, 4 April 2019 5:46:04 AM NZDT Khem Raj wrote:
> On Wed, Apr 3, 2019 at 7:41 AM Tom Rini <trini at konsulko.com> wrote:
> >
> > On Wed, Apr 03, 2019 at 11:30:39AM +0100, Burton, Ross wrote:
> > > On Tue, 2 Apr 2019 at 20:46, Tom Rini <trini at konsulko.com> wrote:
> > > > > The kernel does not have "upgrade foo to the latest upstream
> > > > > version" commits.
> > > > >
> > > > > With the Automatic Upgrade Helper this is a semi-automatic task, and
> > > > > most of the time there is no specific motivation other than
> > > > > upgrading
> > > > > to the latest upstream version.
> > > >
> > > > But since that's just filling in a template the body can also be a
> > > > template perhaps with useful AUH data (run at ... by ... ?) ?
> > >
> > > Apart from making the commit message longer what does this achieve?
> > > The commit already has a timestamp and author.
> >
> > It's an etiquette thing.  Subject+Sign-off+Empty body is bad form.  AUH
> > updates are a form of "trivial update" that every project has.  "Update
> > $X from version $Y to $Z" is what a human would normally put.  It's
> > weird looking at git log of nothing but subject+signed-off-by.  I'm not
> > going to object further on this point, but I don't get it.
> 
> if the content of subject is being repeated in body then I would
> prefer an empty body
> redundant information in commits should be avoided since it can create
> impression that body does not have
> useful information and skip reading it. We should strive to make commits
> concise and useful.

There is often (I won't say always, but often) something useful you can put in 
the commit message. If it's a recipe upgrade, you could put a pointer to the 
upstream changelog in it, for example. As the person doing the upgrade if your 
prior review of that changelog or other upstream release documentation 
indicated any backwards-compatibility issues or CVEs fixed then those really 
ought to be mentioned as well; if you're feeling especially generous you might 
mention highlights of any new functionality. (I have a proposal that might 
help us automate part of that which I've not yet fully fleshed out, hopefully 
one day soon I will get around to it.)

The issue of empty commit messages is something I've complained about in the 
past, and not just about recipe upgrades. If I - as someone who is relatively 
familiar with OE - have to actually read beyond the shortlog / commit message 
to understand the basics of why a change has been made, then it's likely that 
the commit message wasn't good enough. Unlike other issues, once a commit goes 
in the message is set in stone within the git history, so if you are working 
on a change, *please* take a minute or two to document it adequately in the 
commit message so that others looking back can understand it.

Thanks,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre