Re: Patch Submission Guidelines

[Adhemerval Zanella <adhemerval dot zanella at linaro dot org>]

Hi,

On 19-04-2016 06:36, ricaljasan wrote:
> As I prepare my patchset for the manual, I have a few questions about
> how to format the submission.
> 
> It will be of the [PATCH M/N] form, one for each of the chapters.  Is it
> acceptable to use a lengthier and detailed description in 0/N that
> covers everything in all the subsequent patches (these are all
> grammar-related edits), and omit a description in each patch, leaving
> only a title and consistent, terse summary?  For example:
> 
> Grammatical edits to the Error Reporting chapter.
> 
>         * manual/errno.texi: Edit grammar for clarity, consistency, and
>         correctness.

I think it is up to you to make the patch entries consistent and you can
check that some trivial patches only contain the header. For other patches
it will be easier to add the rationale, if any, in the patch description
and any other relevant information, such as links to standard reference,
external discussion, etc.

For grammar and clarity changes in manual I think the changes themselves
shows the intent, so I would not bother for a description. I would add
one if the proposed changes add or remove a topic, move it to somewhere
else, reference to an additional source, etc.

> 
> Also, are ChangeLog entries still necessary?  I recall those being under
> discussion[1,2,3] but am still unclear as to what ever truly became of
> it.  The Contribution checklist[4] mentions them, including the bit
> about editing the file but putting the diff in the message body and not
> the patch.  I see a variety of formats used in practice from a cursory
> look over the past week or so, but the most common appears to be:
> 
> ----
> Detailed message.
> 
> Some kind of header, possibly a name, subject, or date-name-email.
> 
>         * list of changed files
> 
> Attached patch.
> ----
> 
> (with a notable lack of an explicit ChangeLog diff.)  Perhaps there is a
> preferred blend of git format-patch and send-email that will do the
> right thing?

The Changelog is still required and the wiki you posted should contain the
required information to craft one. For patch submission, usually the
Changelog entry is embedded in the patch description (not in diff format).
The format you described is the one I tend to use.

> 
> Thank you,
> Rical
> 
> [1]: https://sourceware.org/ml/libc-alpha/2015-08/msg00889.html
> [2]: https://sourceware.org/ml/libc-alpha/2015-06/msg00051.html
> [3]: https://sourceware.org/ml/libc-alpha/2015-08/msg01279.html
> [4]:
> https://sourceware.org/glibc/wiki/Contribution%20checklist#Properly_Formatted_GNU_ChangeLog
>