From patchwork Wed Jan 22 17:45:06 2020
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: "Richard Earnshaw (lists)"
Your contribution e-mail subject line will become the first line of +the commit message for your patch.
+ +A high-quality e-mail subject line for a contribution contains the +following elements:
+ +The entire line (excluding the classifier) should not exceed 75 +characters.
+ +The classifier identifies the type of contribution, for example a +patch, an RFC (request for comments) or a committed patch (where +approval is not necessary. The classifier should be written in upper +case and surrounded with square brackets. This is the only component +of the e-mail subject line that will not appear in the commit itself. +The classifier may optionally contain a version number (vN) and +a series marker (N/M). Examples are:
+ +[PATCH]
- a single patch[PATCH v2]
- the second version of a single patch[PATCH 3/7]
- the third patch in a series of seven
+ patches[RFC]
- a point of discussion, may contain a patch[COMMITTED]
- a patch that has already been committed.A component tag is a short identifier that identifies the part of +the compiler being modified. This highlights to the relevant +maintainers that the patch may need their attention. Multiple +components may be listed if necessary. Each component tag should be +followed by a colon. For example,
+ +libstdc++:
combine:
vax: testsuite:
Some large components may be subdivided into sub-components. If +the subcomponent name is not disctinct in its own right, you can use the +form component/sub-component:.
+ +The series identifier is optional and is only relevant if a number of +patches are needed in order to effect an overall change. It should be +a short string that identifies the series (it is common to all +patches) and should be followed by a single dash surrounded by white +space.
+ +The brief summary encapsulates in a few words the intent of the
+change. For example: cleanup check_field_decls
.
+Although, very short, the summary should be distinct so that it will
+not be confused with other patches.
If your patch relates a bug in the compiler for which there is an
+existing PR number the bug number should be stated. Use the
+short-form variant [PRnnnnn]
without the bugzilla
+component identifier and with no space between 'PR' and the number.
+The body of the commit message should still contain the full form
+(PR <component>/nnnnn
) within the body of
+the commit message so that Bugzilla will correctly notice the
+commit. If your patch relates to two bugs, then write
+[PRnnnnn, PRmmmmm]
. For multiple
+bugs, just cite the most relevant one in the summary and use an
+elipsis instead of the second, or subsequent PR numbers; list all the
+related PRs in the body of the commit message in the normal way.
It is not necessary to cite bugs that are closed as duplicates of +another unless there is something specific to that report that +is not covered by the parent bug.
+ +Some large patch sets benefit from an introductory e-mail that
+provides more context for the patch series and describes how the
+patches have been broken up to provide for review. The convention is
+that such messages should follow the same format as described above,
+but the patch number should be set to zero, for example: [PATCH
+0/7]
. Remember that the introductory message will not be
+committed with the patches themselves, so it should not contain any
+important information that is not also covered in the individual
+patches. If you send a summary e-mail with a series it is a good idea
+to send the patches as follow-ups (essentially replies) to your
+initial message so that mail software can group the messages
+together.
If you submit a new version of a patch series, then you should +start a new email thread (don't reply to the original patch series). +This avoids email threads becoming confused between discussions of the +first and subsequent revisions of the patch set. Your cover leter +(0/nnn) should explain clearly what has been changed between +the two patch series. Also state if some of the patches are unchanged +between revisions; this saves maintainers having to re-review the +patches they might have already reviewed in an earlier version. The +individual patch messages should be as you expect them to be +committed. It is a good idea to send a final follow-up message to the +original thread indicating that a new version has been submitted.
+ +Here are some complete examples, based on real commits to GCC.
+ +[COMMITTED] libstdc++: Fix freestanding build [PR92376]
[PATCH 1/6] analyzer: Fix tests for UNKNOWN_LOCATION
[RFC] doc: Note that some warnings depend on optimizations [PR92757]
[COMMITTED] c++: coroutines - Initial implementation
[PATCH v2] wwwdocs: E-mail subject lines for contributions
If you do not receive a response to a patch that you have submitted within two weeks or so, it may be a good idea to chase it by sending a -follow-up email to the same list(s). Patches can occasionally fall through -the cracks. Please be sure to include a brief summary of the patch and the -URL of the entry in the mailing list archive of the original submission.
+follow-up e-mail to the same list(s). Patches can occasionally fall +through the cracks. Please be sure to include a brief summary of the +patch and the URL of the entry in the mailing list archive of the +original submission.If you do not have write access and a patch of yours has been approved, but not committed, please advise the approver of that fact. You may want