Re: How to upstream glibc patch?

[Arjun Shankar <arjun dot is at lostca dot se>]

Hi!

> but something is still unclear for me, especially the changelog.
> 
> for example I do like this:
> git format-patch -1
> ../gcc/contrib/mklog my-patch-file
> then I get:
> 
> Unknown ChangeLog:
> 
> 2018-06-08  Hongbo Zhang  <hongbo.zhang@linaro.org>
> 
> * sysdeps/aarch64/multiarch/memcpy.c (libc_ifunc):
> * sysdeps/aarch64/multiarch/memmove.c (libc_ifunc):
> * sysdeps/aarch64/multiarch/memset.c (libc_ifunc):
> * sysdeps/unix/sysv/linux/aarch64/cpu-features.c:
> * sysdeps/unix/sysv/linux/aarch64/cpu-features.h (IS_PHECDA):
> 
> I copy these texts into my patch file as a part of commit message?

The ChangeLog isn't supposed to become part of the commit message. Good
emails sent to the list look something like this:

----------------8<----------------
Subject: [PATCH] This becomes the first line of the commit [BZ #BUGNUMBER]

Here, the submitter explains the change in detail. They may use one or more
paragraphs to explain the change. This content becomes the remaining body of
the commit message.

Next the submitter may make a claim about test results when relevant. The
maintainer checking in your patch will often not add this to the commit
message.

ChangeLog:

YYYY-MM-DD  John Doe  <emailaddress>

	[BZ #BUGNUMBER]
	* foo/bar.c (foobar): New function.
	* foo/zoo.c (fizzbuzz): Check for error before returning.
---
Potentially more notes may follow. e.g. sometimes, when I re-submit a patch
after incorporating review comments, I put a link to discussions around the
older version of the patch here.

<patch content goes here>
----------------8<----------------

The bug numbers in the subject line and ChangeLog are only needed when the
change corresponds to a reported bug or is big enough to be assigned a bug.
Note the TAB characters in the ChangeLog.

What a maintainer does is (either by hand or perhaps with tooling): they
copy the ChangeLog entry to the top of the "ChangeLog" file maintained in
the glibc source tree, and commit it along with the rest of the patch
contents.

> I see it is blank after each colon in the changlog generated above, should
> I add some message manually? or leaving them blank is acceptable?

You should use the space to explain what actually was changed, in short.
Typical entries are new functions, variables, files, or their deletions,
really small summary of how a function was changed, etc. The ChangeLog file
is for users who don't obtain glibc via git, but download a tarball. In the
absence of source control, it becomes their primary tool for knowing what
(in detail) changed in a particular glibc release.

I expect that what I wrote above is in general, good advice. Not all patches
show up in this form, but the above format of email is the one I use, and I
don't recall any reviewer disliking the formatting or asking for it to be
changed. Here's the last patch I sent to this list. It should show the
skeleton I laid out above reproduced in a real example (but literally any
email from the regular maintainers is a good example):
https://sourceware.org/ml/libc-alpha/2018-01/msg00618.html

Cheers,
Arjun