* [wwwdocs] Updates to contribute.html for git-friendly posting rules @ 2020-01-09 10:43 Richard Earnshaw (lists) 2020-01-19 14:47 ` Gerald Pfeifer 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-09 10:43 UTC (permalink / raw) To: gcc-patches [-- Attachment #1: Type: text/plain, Size: 402 bytes --] The thread on gcc@ is now so long and complicated that this proposal back at the start has dropped off the radar. With the switch now imminent I'd like to re-propose this change, this time more formally. The text below draws heavily on the glibc equivalent rules in an attempt to bring some harmony, but it inevitably has some local customizations because these aren't the same project. OK? R. [-- Attachment #2: contribute.patch --] [-- Type: text/x-patch, Size: 3727 bytes --] diff --git a/htdocs/contribute.html b/htdocs/contribute.html index 381aa02a..99d5b73e 100644 --- a/htdocs/contribute.html +++ b/htdocs/contribute.html @@ -262,6 +262,89 @@ that ChangeLog entries may be included as part of the patch and diffs representing new files may be omitted, especially if large, since they can be accessed directly from the repository.)</p> +<h3>Email subject lines</h3> + +Your contribution email subject line will become the first line of the +commit message for your patch. + +A high-quality email subject line for a contribution contains the +following elements: + +<ul> + <li>A classifier</li> + <li>Component tags</li> + <li>An optional series identifier</li> + <li>A brief summary</li> + <li>An optional bug number</li> +</ul> + +<h4>Classifier</h4> + +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 email subject line that will not appear in the commit itself. +The classifier may optionally contain a version number (v<i>N</i>) and +a series marker (<i>N/M</i>). Examples are: + +<ul> + <li><code>[PATCH]</code> - a single patch</li> + <li><code>[PATCH v2]</code> - the second version of a single patch</li> + <li><code>[PATCH 3/7]</code> - the third patch in a series of seven + patches</li> + <li><code>[RFC]</code> - a point of discussion, may contain a patch</li> + <li><code>[COMMITTED]</code> - a patch that has already been committed.</li> +</ul> + +<h4>Component tags</h4> + +A component tag is a short identifier that identifies the part of the +compiler being modified, this is important as it highlights to +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, + +<ul> + <li><code>vax: testsuite:</code></li> + <li><code>libstdc++:</code></li> + <li><code>combine:</code></li> +</ul> + +<h4>Series identifier</h4> + +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 <i>short</i> string that identifies the series (it is common to all +patches) and should be followed by a single dash surrounded by white +space. + +<h4>Brief summary</h4> + +The brief summary encapsulates in a few words the intent of the +change. For example: <code>cleanup check_field_decls</code>. + +<h4>Bug number</h4> + +If your patch fixes a bug in the compiler for which there is an +existing PR number the bug number should be stated. Use the +short-form variant (PR<i>nnnnn</i>) without the bugzilla component +identifier. + +<h4>Other messages</h4> + +Some large patch sets benefit from an introductory email 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: <code>[PATCH +0/7]</code>. 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 email 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. + <h3>Pinging patches, Getting patches applied</h3> <p>If you do not receive a response to a patch that you have submitted ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [wwwdocs] Updates to contribute.html for git-friendly posting rules 2020-01-09 10:43 [wwwdocs] Updates to contribute.html for git-friendly posting rules Richard Earnshaw (lists) @ 2020-01-19 14:47 ` Gerald Pfeifer 2020-01-20 11:54 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Gerald Pfeifer @ 2020-01-19 14:47 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: gcc-patches Hi Richard, On Thu, 9 Jan 2020, Richard Earnshaw (lists) wrote: > The thread on gcc@ is now so long and complicated that this proposal > back at the start has dropped off the radar. With the switch now > imminent I'd like to re-propose this change, this time more formally. I wasn't sure *who* would best approve this since it's more a policy question than anything else, but let's unstall this... There's a general note I'd make, partly based on my going through some of our older web contents recently (and "decluttering" some of it), and some specific feedback. The general note is that we've had a tendency to be very specific in some of our policies (see the last hunk of https://gcc.gnu.org/ml/gcc-patches/2020-01/msg01064.html for an example) which can make appear us not very inviting to new blood. That is, if all I wanted is to submit a simple patch for a typo somewhere, how would I feel about our set of instructions, and now this addition? Is there a way to make this more light weight or less complex/ optional for simple contributions? +<h3>Email subject lines</h3> If I interpret both Merriam-Webster and the OED correctly, "e-mail" is the preferrable spelling? +Your contribution email subject line will become the first line of the +commit message for your patch. <p> ... </p> around paragraphs (throughout). +<h4>Classifier</h4> + +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 email subject line that will not appear in the commit itself. +The classifier may optionally contain a version number (v<i>N</i>) and +a series marker (<i>N/M</i>). Examples are: + +<ul> + <li><code>[PATCH]</code> - a single patch</li> + <li><code>[PATCH v2]</code> - the second version of a single patch</li> + <li><code>[PATCH 3/7]</code> - the third patch in a series of seven + patches</li> + <li><code>[RFC]</code> - a point of discussion, may contain a patch</li> + <li><code>[COMMITTED]</code> - a patch that has already been committed.</li> +</ul> I see a lot of [C++], [aarch64], [fortran], [wwwdocs] ;-),... in our archives. Should this all really move into the remainder of the subject line/ first line of the commit message? I guess this is a key part change as part of your proposal? +<h4>Component tags</h4> Alternately we could use [PATCH,fortran], [committed,C++],... ? Actually, if we use PATCH, RFC,... for everything else, could COMMITTED be omitted? That feels like a bit of shouting (so if we keep that, at least make it lower case)? +A component tag is a short identifier that identifies the part of the +compiler being modified, this is important as it highlights to Full stop: "...modified. This is..." or, better "...modified. This highlights..." which is shorter. I believe this could benefit from some examples of overall subject lines. In fact, perhaps start with examples and describe the individual components? As for next steps, can you please mail the (updated) proposal to the gcc@ list? Some, even quite prominent contributors, do not follow gcc-patches at all (or not close) and this is bigger policy question that will be interesting to the broad group. Hope this helps, Gerald ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [wwwdocs] Updates to contribute.html for git-friendly posting rules 2020-01-19 14:47 ` Gerald Pfeifer @ 2020-01-20 11:54 ` Richard Earnshaw (lists) 2020-01-21 15:04 ` [PATCH, v2] wwwdocs: e-mail subject lines for contributions Richard Earnshaw (lists) 2020-02-03 15:34 ` [wwwdocs] Updates to contribute.html for git-friendly posting rules Segher Boessenkool 0 siblings, 2 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-20 11:54 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: gcc-patches On 19/01/2020 14:09, Gerald Pfeifer wrote: > Hi Richard, > > On Thu, 9 Jan 2020, Richard Earnshaw (lists) wrote: >> The thread on gcc@ is now so long and complicated that this proposal >> back at the start has dropped off the radar. With the switch now >> imminent I'd like to re-propose this change, this time more formally. > > I wasn't sure *who* would best approve this since it's more a policy > question than anything else, but let's unstall this... > > > There's a general note I'd make, partly based on my going through > some of our older web contents recently (and "decluttering" some > of it), and some specific feedback. > > > The general note is that we've had a tendency to be very specific > in some of our policies (see the last hunk of > https://gcc.gnu.org/ml/gcc-patches/2020-01/msg01064.html for an > example) which can make appear us not very inviting to new blood. > > That is, if all I wanted is to submit a simple patch for a typo > somewhere, how would I feel about our set of instructions, and > now this addition? > > Is there a way to make this more light weight or less complex/ > optional for simple contributions? The more we make the process lightweight for contributors, the more work we make for maintainers. If the contribution is sent correctly, then ideally, the patch can be applied with just 'git am' by the maintainer. So while we shouldn't overburden things, we shouldn't go too far. I don't think we've added anything that glibc don't already require, for example, or many other git-based development communities. > > > +<h3>Email subject lines</h3> > > If I interpret both Merriam-Webster and the OED correctly, "e-mail" > is the preferrable spelling? > > +Your contribution email subject line will become the first line of the > +commit message for your patch. > Changed - I note that there are some other uses of 'email' on the web pages. I'm not fixing those. > <p> ... </p> around paragraphs (throughout). > Done. > +<h4>Classifier</h4> > + > +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 email subject line that will not appear in the commit itself. > +The classifier may optionally contain a version number (v<i>N</i>) and > +a series marker (<i>N/M</i>). Examples are: > + > +<ul> > + <li><code>[PATCH]</code> - a single patch</li> > + <li><code>[PATCH v2]</code> - the second version of a single patch</li> > + <li><code>[PATCH 3/7]</code> - the third patch in a series of seven > + patches</li> > + <li><code>[RFC]</code> - a point of discussion, may contain a patch</li> > + <li><code>[COMMITTED]</code> - a patch that has already been committed.</li> > +</ul> > > I see a lot of [C++], [aarch64], [fortran], [wwwdocs] ;-),... in > our archives. the [] annotation makes life harder for 'git am' as it automatically strips such prefixes when applying the patch. 'git am --keep-non-patch' can avoid stripping such tags, but it's a bit of a mouthful to keep typing it. Git communities (including glibc) generally use <topic>: these days, so this aligns with that. > > Should this all really move into the remainder of the subject line/ > first line of the commit message? I guess this is a key part change > as part of your proposal? > The point is to get a good, concise summary that appears in "git log --oneline" showing the history of commits. Moving it to the body breaks that. > +<h4>Component tags</h4> > > Alternately we could use [PATCH,fortran], [committed,C++],... ? > Please, no. See comment about stripping above. > > Actually, if we use PATCH, RFC,... for everything else, could > COMMITTED be omitted? That feels like a bit of shouting (so if > we keep that, at least make it lower case)? > This is about consistency across the communities that use git. > > +A component tag is a short identifier that identifies the part of the > +compiler being modified, this is important as it highlights to > > Full stop: "...modified. This is..." or, better "...modified. This > highlights..." which is shorter. > Fixed. > > I believe this could benefit from some examples of overall subject > lines. In fact, perhaps start with examples and describe the individual > components? > > > As for next steps, can you please mail the (updated) proposal to > the gcc@ list? Some, even quite prominent contributors, do not > follow gcc-patches at all (or not close) and this is bigger policy > question that will be interesting to the broad group. > I sent the proposal to gcc@ last year on the basis that this was policy rather than a simple technical change, but it didn't make any progress (the thread got rather bogged down with other unrelated discussions). Anyway, patches are supposed to go to gcc-patches, even for the web pages, aren't they? I'll send the update to both lists... R. > Hope this helps, > Gerald > ^ permalink raw reply [flat|nested] 53+ messages in thread
* [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-20 11:54 ` Richard Earnshaw (lists) @ 2020-01-21 15:04 ` Richard Earnshaw (lists) 2020-01-21 15:10 ` Jakub Jelinek ` (2 more replies) 2020-02-03 15:34 ` [wwwdocs] Updates to contribute.html for git-friendly posting rules Segher Boessenkool 1 sibling, 3 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-21 15:04 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: gcc-patches, GCC Development [-- Attachment #1: Type: text/plain, Size: 1000 bytes --] [updated, following some comments from Gerald, main differences are slight tweaks to the html markup and changing "email" to "e-mail"] This patch proposes some new (additional) rules for email subject lines when contributing to GCC. The goal is to make sure that, as far as possible, the subject for a patch will form a good summary when the message is committed to the repository if applied with 'git am'. Where possible, I've tried to align these rules with those already in use for glibc, so that the differences are minimal and only where necessary. Some things that differ from existing practice (at least by some people) are: - Use '<topic>:' rather than '[<topic>]' - This is more git friendly and works with 'git am'. - Put bug numbers at the end of the line rather than the beginning. - The bug number is useful, but not as useful as the brief summary. Also, use the shortened form, as the topic part is more usefully conveyed in the proper topic field (see above). [-- Attachment #2: contrib.patch --] [-- Type: text/x-patch, Size: 4469 bytes --] diff --git a/htdocs/contribute.html b/htdocs/contribute.html index 042ff069..861f7e5e 100644 --- a/htdocs/contribute.html +++ b/htdocs/contribute.html @@ -249,13 +249,98 @@ that ChangeLog entries may be included as part of the patch and diffs representing new files may be omitted, especially if large, since they can be accessed directly from the repository.)</p> +<h3>E-mail subject lines</h3> + +<p>Your contribution e-mail subject line will become the first line of +the commit message for your patch.</p> + +<p>A high-quality e-mail subject line for a contribution contains the +following elements:</p> + +<ul> + <li>A classifier</li> + <li>Component tags</li> + <li>An optional series identifier</li> + <li>A brief summary</li> + <li>An optional bug number</li> +</ul> + +<h4>Classifier</h4> + +<p>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 (v<i>N</i>) and +a series marker (<i>N/M</i>). Examples are:</p> + +<ul> + <li><code>[PATCH]</code> - a single patch</li> + <li><code>[PATCH v2]</code> - the second version of a single patch</li> + <li><code>[PATCH 3/7]</code> - the third patch in a series of seven + patches</li> + <li><code>[RFC]</code> - a point of discussion, may contain a patch</li> + <li><code>[COMMITTED]</code> - a patch that has already been committed.</li> +</ul> + +<h4>Component tags</h4> + +<p>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,</p> + +<ul> + <li><code>libstdc++:</code></li> + <li><code>combine:</code></li> + <li><code>vax: testsuite:</code></li> +</ul> + +<h4>Series identifier</h4> + +<p>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 <i>short</i> string that identifies the series (it is common to all +patches) and should be followed by a single dash surrounded by white +space.</p> + +<h4>Brief summary</h4> + +<p>The brief summary encapsulates in a few words the intent of the +change. For example: <code>cleanup check_field_decls</code>.</p> + +<h4>Bug number</h4> + +<p>If your patch fixes a bug in the compiler for which there is an +existing PR number the bug number should be stated. Use the +short-form variant (PR<i>nnnnn</i>) without the bugzilla component +identifier.</p> + +<h4>Other messages</h4> + +<p>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: <code>[PATCH +0/7]</code>. 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.</p> + <h3>Pinging patches, Getting patches applied</h3> <p>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.</p> +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.</p> <p>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 ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 15:04 ` [PATCH, v2] wwwdocs: e-mail subject lines for contributions Richard Earnshaw (lists) @ 2020-01-21 15:10 ` Jakub Jelinek 2020-01-21 15:34 ` Richard Earnshaw (lists) 2020-01-21 20:17 ` Segher Boessenkool 2020-01-22 19:15 ` [PATCH, v3] " Richard Earnshaw (lists) 2 siblings, 1 reply; 53+ messages in thread From: Jakub Jelinek @ 2020-01-21 15:10 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches, GCC Development On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: > [updated, following some comments from Gerald, main differences are > slight tweaks to the html markup and changing "email" to "e-mail"] > > This patch proposes some new (additional) rules for email subject lines > when contributing to GCC. The goal is to make sure that, as far as > possible, the subject for a patch will form a good summary when the > message is committed to the repository if applied with 'git am'. Where > possible, I've tried to align these rules with those already in > use for glibc, so that the differences are minimal and only where > necessary. > > Some things that differ from existing practice (at least by some people) > are: > > - Use '<topic>:' rather than '[<topic>]' > - This is more git friendly and works with 'git am'. > - Put bug numbers at the end of the line rather than the beginning. > - The bug number is useful, but not as useful as the brief summary. > Also, use the shortened form, as the topic part is more usefully > conveyed in the proper topic field (see above). Some examples would be useful I'd say, e.g. it is unclear in what way you want the PR number to be appended, shall it be something: whatever words describe it PR12345 or something: whatever words describe it (PR12345) or something: whatever words describe it: PR12345 or something: whatever words describe it [PR12345] or something else? Also, it would be nice to stress that the PR long form should be in the ChangeLog and somewhere on the later lines of the commit message, I don't think we pick up the shorter form from the first line when it short form (I could be wrong, but e.g. https://gcc.gnu.org/g:865257c447cc50f5819e9b53da83145f3c36c305 commit didn't make it into bugzilla). Jakub ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 15:10 ` Jakub Jelinek @ 2020-01-21 15:34 ` Richard Earnshaw (lists) 2020-01-21 16:26 ` Jakub Jelinek 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-21 15:34 UTC (permalink / raw) To: Jakub Jelinek; +Cc: Gerald Pfeifer, gcc-patches, GCC Development On 21/01/2020 15:04, Jakub Jelinek wrote: > On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: >> [updated, following some comments from Gerald, main differences are >> slight tweaks to the html markup and changing "email" to "e-mail"] >> >> This patch proposes some new (additional) rules for email subject lines >> when contributing to GCC. The goal is to make sure that, as far as >> possible, the subject for a patch will form a good summary when the >> message is committed to the repository if applied with 'git am'. Where >> possible, I've tried to align these rules with those already in >> use for glibc, so that the differences are minimal and only where >> necessary. >> >> Some things that differ from existing practice (at least by some people) >> are: >> >> - Use '<topic>:' rather than '[<topic>]' >> - This is more git friendly and works with 'git am'. >> - Put bug numbers at the end of the line rather than the beginning. >> - The bug number is useful, but not as useful as the brief summary. >> Also, use the shortened form, as the topic part is more usefully >> conveyed in the proper topic field (see above). > > Some examples would be useful I'd say, e.g. it is unclear in what way you > want the PR number to be appended, shall it be > something: whatever words describe it PR12345 > or > something: whatever words describe it (PR12345) > or > something: whatever words describe it: PR12345 > or > something: whatever words describe it [PR12345] > or something else? Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm not too worried. I'd be happy with [PR #nnnn], but if folk want something else, please say so quickly... I'll prepare an edit for that... > > Also, it would be nice to stress that the PR long form should be in the > ChangeLog and somewhere on the later lines of the commit message, I don't > think we pick up the shorter form from the first line when it short form (I > could be wrong, but e.g. > https://gcc.gnu.org/g:865257c447cc50f5819e9b53da83145f3c36c305 > commit didn't make it into bugzilla). > Yes, good point. Thanks. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 15:34 ` Richard Earnshaw (lists) @ 2020-01-21 16:26 ` Jakub Jelinek 2020-01-21 16:26 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Jakub Jelinek @ 2020-01-21 16:26 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches, GCC Development On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) wrote: > > Some examples would be useful I'd say, e.g. it is unclear in what way you > > want the PR number to be appended, shall it be > > something: whatever words describe it PR12345 > > or > > something: whatever words describe it (PR12345) > > or > > something: whatever words describe it: PR12345 > > or > > something: whatever words describe it [PR12345] > > or something else? > > Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm not > too worried. I'd be happy with [PR #nnnn], but if folk want something else, > please say so quickly... [PR 12345] or [PR #12345] is bad, because the bugzilla won't underline it, it needs to be either PR12345 word, or PR component/12345 . Jakub ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 16:26 ` Jakub Jelinek @ 2020-01-21 16:26 ` Richard Earnshaw (lists) 2020-01-21 18:32 ` Jason Merrill 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-21 16:26 UTC (permalink / raw) To: Jakub Jelinek; +Cc: Gerald Pfeifer, gcc-patches, GCC Development On 21/01/2020 15:39, Jakub Jelinek wrote: > On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) wrote: >>> Some examples would be useful I'd say, e.g. it is unclear in what way you >>> want the PR number to be appended, shall it be >>> something: whatever words describe it PR12345 >>> or >>> something: whatever words describe it (PR12345) >>> or >>> something: whatever words describe it: PR12345 >>> or >>> something: whatever words describe it [PR12345] >>> or something else? >> >> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm not >> too worried. I'd be happy with [PR #nnnn], but if folk want something else, >> please say so quickly... > > [PR 12345] or [PR #12345] is bad, because the bugzilla won't underline it, > it needs to be either PR12345 word, or PR component/12345 . > > Jakub > ok, lets go with [PRnnnn] then. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 16:26 ` Richard Earnshaw (lists) @ 2020-01-21 18:32 ` Jason Merrill 2020-01-21 19:09 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Jason Merrill @ 2020-01-21 18:32 UTC (permalink / raw) To: Richard Earnshaw (lists), Jakub Jelinek Cc: Gerald Pfeifer, gcc-patches, GCC Development On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote: > On 21/01/2020 15:39, Jakub Jelinek wrote: >> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) wrote: >>>> Some examples would be useful I'd say, e.g. it is unclear in what >>>> way you >>>> want the PR number to be appended, shall it be >>>> something: whatever words describe it PR12345 >>>> or >>>> something: whatever words describe it (PR12345) >>>> or >>>> something: whatever words describe it: PR12345 >>>> or >>>> something: whatever words describe it [PR12345] >>>> or something else? >>> >>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, I'm >>> not >>> too worried. I'd be happy with [PR #nnnn], but if folk want >>> something else, >>> please say so quickly... >> >> [PR 12345] or [PR #12345] is bad, because the bugzilla won't underline >> it, >> it needs to be either PR12345 word, or PR component/12345 . > > ok, lets go with [PRnnnn] then. Doesn't this use of [] have the same problem with git am? My summaries are often describing the bug I'm fixing, i.e. [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs. which is also the first line of my ChangeLog entry. I think you are proposing [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs (PR91476) which can no longer be shared with the ChangeLog. Jason ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 18:32 ` Jason Merrill @ 2020-01-21 19:09 ` Richard Earnshaw (lists) 2020-01-22 9:35 ` Jakub Jelinek 2020-01-22 16:27 ` Richard Sandiford 0 siblings, 2 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-21 19:09 UTC (permalink / raw) To: Jason Merrill, Jakub Jelinek; +Cc: Gerald Pfeifer, gcc-patches, GCC Development On 21/01/2020 17:20, Jason Merrill wrote: > On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote: >> On 21/01/2020 15:39, Jakub Jelinek wrote: >>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) >>> wrote: >>>>> Some examples would be useful I'd say, e.g. it is unclear in what >>>>> way you >>>>> want the PR number to be appended, shall it be >>>>> something: whatever words describe it PR12345 >>>>> or >>>>> something: whatever words describe it (PR12345) >>>>> or >>>>> something: whatever words describe it: PR12345 >>>>> or >>>>> something: whatever words describe it [PR12345] >>>>> or something else? >>>> >>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, >>>> I'm not >>>> too worried. I'd be happy with [PR #nnnn], but if folk want >>>> something else, >>>> please say so quickly... >>> >>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't >>> underline it, >>> it needs to be either PR12345 word, or PR component/12345 . >> >> ok, lets go with [PRnnnn] then. > > Doesn't this use of [] have the same problem with git am? No, because only 'leading' [] blocks are removed - git mailinfo --help > > My summaries are often describing the bug I'm fixing, i.e. > > [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs. > > which is also the first line of my ChangeLog entry. I think you are > proposing > > [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs > (PR91476) > > which can no longer be shared with the ChangeLog. > I was trying to unify this with glibc. They specify the bug number at the end of the line. We can diverge if it's generally felt to be important, but details like this create needless friction for folk working in both communities. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 19:09 ` Richard Earnshaw (lists) @ 2020-01-22 9:35 ` Jakub Jelinek 2020-01-22 10:00 ` Richard Earnshaw (lists) 2020-01-22 16:27 ` Richard Sandiford 1 sibling, 1 reply; 53+ messages in thread From: Jakub Jelinek @ 2020-01-22 9:35 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Jason Merrill, Gerald Pfeifer, gcc-patches, GCC Development On Tue, Jan 21, 2020 at 06:50:13PM +0000, Richard Earnshaw (lists) wrote: > > Doesn't this use of [] have the same problem with git am? > > No, because only 'leading' [] blocks are removed - git mailinfo --help I've used openmp: Teach omp_code_to_statement about rest of OpenMP statements [PR93329] as the first line of a commit log and that [PR93329] part is completely gone from it. Jakub ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-22 9:35 ` Jakub Jelinek @ 2020-01-22 10:00 ` Richard Earnshaw (lists) 2020-01-22 10:04 ` Jakub Jelinek 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-22 10:00 UTC (permalink / raw) To: Jakub Jelinek; +Cc: Jason Merrill, Gerald Pfeifer, gcc-patches, GCC Development On 22/01/2020 09:07, Jakub Jelinek wrote: > On Tue, Jan 21, 2020 at 06:50:13PM +0000, Richard Earnshaw (lists) wrote: >>> Doesn't this use of [] have the same problem with git am? >> >> No, because only 'leading' [] blocks are removed - git mailinfo --help > > I've used > openmp: Teach omp_code_to_statement about rest of OpenMP statements [PR93329] > as the first line of a commit log and that [PR93329] part is completely gone > from it. > > Jakub > How did you apply the patch? R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-22 10:00 ` Richard Earnshaw (lists) @ 2020-01-22 10:04 ` Jakub Jelinek 0 siblings, 0 replies; 53+ messages in thread From: Jakub Jelinek @ 2020-01-22 10:04 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Jason Merrill, Gerald Pfeifer, gcc-patches, GCC Development On Wed, Jan 22, 2020 at 09:35:31AM +0000, Richard Earnshaw (lists) wrote: > On 22/01/2020 09:07, Jakub Jelinek wrote: > > On Tue, Jan 21, 2020 at 06:50:13PM +0000, Richard Earnshaw (lists) wrote: > > > > Doesn't this use of [] have the same problem with git am? > > > > > > No, because only 'leading' [] blocks are removed - git mailinfo --help > > > > I've used > > openmp: Teach omp_code_to_statement about rest of OpenMP statements [PR93329] > > as the first line of a commit log and that [PR93329] part is completely gone > > from it. > > How did you apply the patch? Just git commit -a and editing the log message. But I got the [PR.....] not eaten in another commit, so ignore the above for now (although I'm very much convinced it was in there when I wrote the commit log). Jakub ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 19:09 ` Richard Earnshaw (lists) 2020-01-22 9:35 ` Jakub Jelinek @ 2020-01-22 16:27 ` Richard Sandiford 2020-01-22 17:02 ` Marek Polacek 1 sibling, 1 reply; 53+ messages in thread From: Richard Sandiford @ 2020-01-22 16:27 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Jason Merrill, Jakub Jelinek, Gerald Pfeifer, gcc-patches, GCC Development "Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> writes: > On 21/01/2020 17:20, Jason Merrill wrote: >> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote: >>> On 21/01/2020 15:39, Jakub Jelinek wrote: >>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) >>>> wrote: >>>>>> Some examples would be useful I'd say, e.g. it is unclear in what >>>>>> way you >>>>>> want the PR number to be appended, shall it be >>>>>> something: whatever words describe it PR12345 >>>>>> or >>>>>> something: whatever words describe it (PR12345) >>>>>> or >>>>>> something: whatever words describe it: PR12345 >>>>>> or >>>>>> something: whatever words describe it [PR12345] >>>>>> or something else? >>>>> >>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, >>>>> I'm not >>>>> too worried. I'd be happy with [PR #nnnn], but if folk want >>>>> something else, >>>>> please say so quickly... >>>> >>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't >>>> underline it, >>>> it needs to be either PR12345 word, or PR component/12345 . >>> >>> ok, lets go with [PRnnnn] then. >> >> Doesn't this use of [] have the same problem with git am? > > No, because only 'leading' [] blocks are removed - git mailinfo --help > >> >> My summaries are often describing the bug I'm fixing, i.e. >> >> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs. >> >> which is also the first line of my ChangeLog entry. I think you are >> proposing >> >> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs >> (PR91476) >> >> which can no longer be shared with the ChangeLog. >> > > I was trying to unify this with glibc. They specify the bug number at > the end of the line. > > We can diverge if it's generally felt to be important, but details like > this create needless friction for folk working in both communities. +1 for "component: Summary [PRnnnnn]" FWIW. PR bz-component/nnnnn works well for C++. The problem is that so many other PRs come under tree-optimization and rtl-optimization, which eat up a lot of subject line characters without narrowing things down very much. "cselib: ... [PRnnnnn]" is both shorter and more descriptive than "PR rtl-optimization/nnnnn - ....", etc. Same idea for "PR target/nnnnn - ...": you then need to say which target you mean in the main summary, whereas "aarch64: .... [PRnnnnn]" makes it easier to keep the main summary short. Maybe that's just a problem with the bz classification though... Richard ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-22 16:27 ` Richard Sandiford @ 2020-01-22 17:02 ` Marek Polacek 2020-01-22 17:10 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Marek Polacek @ 2020-01-22 17:02 UTC (permalink / raw) To: Richard Earnshaw (lists), Jason Merrill, Jakub Jelinek, Gerald Pfeifer, gcc-patches, GCC Development, richard.sandiford On Wed, Jan 22, 2020 at 04:05:37PM +0000, Richard Sandiford wrote: > "Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> writes: > > On 21/01/2020 17:20, Jason Merrill wrote: > >> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote: > >>> On 21/01/2020 15:39, Jakub Jelinek wrote: > >>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) > >>>> wrote: > >>>>>> Some examples would be useful I'd say, e.g. it is unclear in what > >>>>>> way you > >>>>>> want the PR number to be appended, shall it be > >>>>>> something: whatever words describe it PR12345 > >>>>>> or > >>>>>> something: whatever words describe it (PR12345) > >>>>>> or > >>>>>> something: whatever words describe it: PR12345 > >>>>>> or > >>>>>> something: whatever words describe it [PR12345] > >>>>>> or something else? > >>>>> > >>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, > >>>>> I'm not > >>>>> too worried. I'd be happy with [PR #nnnn], but if folk want > >>>>> something else, > >>>>> please say so quickly... > >>>> > >>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't > >>>> underline it, > >>>> it needs to be either PR12345 word, or PR component/12345 . > >>> > >>> ok, lets go with [PRnnnn] then. > >> > >> Doesn't this use of [] have the same problem with git am? > > > > No, because only 'leading' [] blocks are removed - git mailinfo --help > > > >> > >> My summaries are often describing the bug I'm fixing, i.e. > >> > >> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs. > >> > >> which is also the first line of my ChangeLog entry. I think you are > >> proposing > >> > >> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs > >> (PR91476) > >> > >> which can no longer be shared with the ChangeLog. > >> > > > > I was trying to unify this with glibc. They specify the bug number at > > the end of the line. > > > > We can diverge if it's generally felt to be important, but details like > > this create needless friction for folk working in both communities. > > +1 for "component: Summary [PRnnnnn]" FWIW. > > PR bz-component/nnnnn works well for C++. The problem is that so many > other PRs come under tree-optimization and rtl-optimization, which > eat up a lot of subject line characters without narrowing things down > very much. "cselib: ... [PRnnnnn]" is both shorter and more descriptive > than "PR rtl-optimization/nnnnn - ....", etc. Yeah, the cselib version definitely looks preferable to me. What if a patch touches more than just the C++ FE, do we want "c,c++:"? Though kernel uses net: sched: act_ctinfo: fix memory leak locking/rwsem: Fix kernel crash when spinning on RWSEM_OWNER_UNKNOWN If a patch touches various spots in the optimizers, maybe we can just go with "tree-opt:" or "rtl:"? Further, I suppose multiple PRs fixed by a single patch would look like: c++: Implement DR 666 [PR57, PR12345] Marek ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-22 17:02 ` Marek Polacek @ 2020-01-22 17:10 ` Richard Earnshaw (lists) 0 siblings, 0 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-22 17:10 UTC (permalink / raw) To: Marek Polacek, Jason Merrill, Jakub Jelinek, Gerald Pfeifer, gcc-patches, GCC Development, richard.sandiford On 22/01/2020 16:28, Marek Polacek wrote: > On Wed, Jan 22, 2020 at 04:05:37PM +0000, Richard Sandiford wrote: >> "Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> writes: >>> On 21/01/2020 17:20, Jason Merrill wrote: >>>> On 1/21/20 10:40 AM, Richard Earnshaw (lists) wrote: >>>>> On 21/01/2020 15:39, Jakub Jelinek wrote: >>>>>> On Tue, Jan 21, 2020 at 03:33:22PM +0000, Richard Earnshaw (lists) >>>>>> wrote: >>>>>>>> Some examples would be useful I'd say, e.g. it is unclear in what >>>>>>>> way you >>>>>>>> want the PR number to be appended, shall it be >>>>>>>> something: whatever words describe it PR12345 >>>>>>>> or >>>>>>>> something: whatever words describe it (PR12345) >>>>>>>> or >>>>>>>> something: whatever words describe it: PR12345 >>>>>>>> or >>>>>>>> something: whatever words describe it [PR12345] >>>>>>>> or something else? >>>>>>> >>>>>>> Glibc use "[BZ #nnnn]" - obviously BZ becomes PR, but after that, >>>>>>> I'm not >>>>>>> too worried. I'd be happy with [PR #nnnn], but if folk want >>>>>>> something else, >>>>>>> please say so quickly... >>>>>> >>>>>> [PR 12345] or [PR #12345] is bad, because the bugzilla won't >>>>>> underline it, >>>>>> it needs to be either PR12345 word, or PR component/12345 . >>>>> >>>>> ok, lets go with [PRnnnn] then. >>>> >>>> Doesn't this use of [] have the same problem with git am? >>> >>> No, because only 'leading' [] blocks are removed - git mailinfo --help >>> >>>> >>>> My summaries are often describing the bug I'm fixing, i.e. >>>> >>>> [PATCH] PR c++/91476 - anon-namespace reference temp clash between TUs. >>>> >>>> which is also the first line of my ChangeLog entry. I think you are >>>> proposing >>>> >>>> [COMMITTED] c++: Fix anon-namespace reference temp clash between TUs >>>> (PR91476) >>>> >>>> which can no longer be shared with the ChangeLog. >>>> >>> >>> I was trying to unify this with glibc. They specify the bug number at >>> the end of the line. >>> >>> We can diverge if it's generally felt to be important, but details like >>> this create needless friction for folk working in both communities. >> >> +1 for "component: Summary [PRnnnnn]" FWIW. >> >> PR bz-component/nnnnn works well for C++. The problem is that so many >> other PRs come under tree-optimization and rtl-optimization, which >> eat up a lot of subject line characters without narrowing things down >> very much. "cselib: ... [PRnnnnn]" is both shorter and more descriptive >> than "PR rtl-optimization/nnnnn - ....", etc. > > Yeah, the cselib version definitely looks preferable to me. > > What if a patch touches more than just the C++ FE, do we want "c,c++:"? c-common: or c-family:? > Though kernel uses > > net: sched: act_ctinfo: fix memory leak I'd read that as a patch that crosses the three separate components. > locking/rwsem: Fix kernel crash when spinning on RWSEM_OWNER_UNKNOWN And this would be a patch that affectst the rwsem sub-component of locking. > > If a patch touches various spots in the optimizers, maybe we can > just go with "tree-opt:" or "rtl:"? > Not sure we want to get that prescriptive. Things are likely to change around anyway. rtl: would suggest it was one of the non-specific rtl-related issues, tree: similarly for a tree-related issue. > Further, I suppose multiple PRs fixed by a single patch would look like: > > c++: Implement DR 666 [PR57, PR12345] Depends on the overall context. In the subject line I think it would be acceptable to reference just one, perhaps two PRs. If there are more, then something like [PRnnn, ...] would probably be an acceptable way of showing that more were referenced later in the body. > > Marek > ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 15:04 ` [PATCH, v2] wwwdocs: e-mail subject lines for contributions Richard Earnshaw (lists) 2020-01-21 15:10 ` Jakub Jelinek @ 2020-01-21 20:17 ` Segher Boessenkool 2020-01-22 10:14 ` Richard Earnshaw (lists) 2020-01-22 19:15 ` [PATCH, v3] " Richard Earnshaw (lists) 2 siblings, 1 reply; 53+ messages in thread From: Segher Boessenkool @ 2020-01-21 20:17 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches, GCC Development Hi! Thanks for doing this. On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: > This patch proposes some new (additional) rules for email subject lines > when contributing to GCC. The goal is to make sure that, as far as > possible, the subject for a patch will form a good summary when the > message is committed to the repository if applied with 'git am'. > +<p>A high-quality e-mail subject line for a contribution contains the > +following elements:</p> > + <li>A brief summary</li> You could stress that this is the one thing that really matters. And it's not a summary, it's much too brief for that (at most ~50 chars), but yup it should be something that allows *a human* to identify what this is. Everything else is just convention. > +<p>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. Often people use aaa/bbb: if drilling down a bit that way helps keep the subject short (which is the *point* of all this: keep things better consumable for humans). > +<p>The brief summary encapsulates in a few words the intent of the > +change. For example: <code>cleanup check_field_decls</code>.</p> It should start with a capital though. "Clean up blablal". (So no dot to end the sentence, this isn't a sentence). A capital helps the reader to quickly identify what is what, separate fluff from the core parts. > +<p>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. All non-trivial series, yeah. Maybe we should mention how v2 etc. of patch series should show what is changed? If there is a good standard practice for that at all :-) Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-21 20:17 ` Segher Boessenkool @ 2020-01-22 10:14 ` Richard Earnshaw (lists) 2020-01-22 14:06 ` Segher Boessenkool 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-22 10:14 UTC (permalink / raw) To: Segher Boessenkool; +Cc: Gerald Pfeifer, gcc-patches, GCC Development On 21/01/2020 19:26, Segher Boessenkool wrote: > Hi! > > Thanks for doing this. > > On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: >> This patch proposes some new (additional) rules for email subject lines >> when contributing to GCC. The goal is to make sure that, as far as >> possible, the subject for a patch will form a good summary when the >> message is committed to the repository if applied with 'git am'. > >> +<p>A high-quality e-mail subject line for a contribution contains the >> +following elements:</p> > >> + <li>A brief summary</li> > > You could stress that this is the one thing that really matters. And > it's not a summary, it's much too brief for that (at most ~50 chars), > but yup it should be something that allows *a human* to identify what > this is. > Well, it should all matter, or why are we requiring it? I'm happy to insert 'very' in front of 'brief' and to say elsewhere that the entire subject (less the leading [...] part, should rarely, if ever, go beyond 80 characters. > Everything else is just convention. > >> +<p>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. > > Often people use aaa/bbb: if drilling down a bit that way helps keep the > subject short (which is the *point* of all this: keep things better > consumable for humans). The aaa: bbb: is really for when aaa and bbb are independent parts of the compiler and potentially needs multiple reviewers. aaa/bbb is when bbb is strictly a sub-component of aaa (for example, arm/SVE: would be an SVE related issue in the arm backend). I'm certainly not against having that. > >> +<p>The brief summary encapsulates in a few words the intent of the >> +change. For example: <code>cleanup check_field_decls</code>.</p> > > It should start with a capital though. "Clean up blablal". (So no > dot to end the sentence, this isn't a sentence). A capital helps > the reader to quickly identify what is what, separate fluff from the > core parts. > There is a balance here to be made. I'm mindful of Gerald's concern that this is perhaps overly restrictive for new users already. I certainly think we should have a good house style, but getting too prescriptive just gets in the way of attracting good contributions. >> +<p>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. > > All non-trivial series, yeah. > > Maybe we should mention how v2 etc. of patch series should show what is > changed? If there is a good standard practice for that at all :-) > Dunno. I think that belongs primarily in the v2 0/n mail. It's not, after all, something that needs to be kept once the patches are applied. R. > > Segher > ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v2] wwwdocs: e-mail subject lines for contributions 2020-01-22 10:14 ` Richard Earnshaw (lists) @ 2020-01-22 14:06 ` Segher Boessenkool 0 siblings, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-01-22 14:06 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches, GCC Development On Wed, Jan 22, 2020 at 10:00:00AM +0000, Richard Earnshaw (lists) wrote: > On 21/01/2020 19:26, Segher Boessenkool wrote: > >On Tue, Jan 21, 2020 at 02:52:00PM +0000, Richard Earnshaw (lists) wrote: > >>+ <li>A brief summary</li> > > > >You could stress that this is the one thing that really matters. And > >it's not a summary, it's much too brief for that (at most ~50 chars), > >but yup it should be something that allows *a human* to identify what > >this is. > > > > Well, it should all matter, or why are we requiring it? Yes. > I'm happy to insert 'very' in front of 'brief' and to say elsewhere that > the entire subject (less the leading [...] part, should rarely, if ever, > go beyond 80 characters. The usual recommendation is 50 chars. Which is just about right with most MUAs. > >Everything else is just convention. > > > >>+<p>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. > > > >Often people use aaa/bbb: if drilling down a bit that way helps keep the > >subject short (which is the *point* of all this: keep things better > >consumable for humans). > > The aaa: bbb: is really for when aaa and bbb are independent parts of > the compiler and potentially needs multiple reviewers. aaa/bbb is when > bbb is strictly a sub-component of aaa (for example, arm/SVE: would be > an SVE related issue in the arm backend). I'm certainly not against > having that. Excellent. > >>+<p>The brief summary encapsulates in a few words the intent of the > >>+change. For example: <code>cleanup check_field_decls</code>.</p> > > > >It should start with a capital though. "Clean up blablal". (So no > >dot to end the sentence, this isn't a sentence). A capital helps > >the reader to quickly identify what is what, separate fluff from the > >core parts. > > There is a balance here to be made. I'm mindful of Gerald's concern > that this is perhaps overly restrictive for new users already. I > certainly think we should have a good house style, but getting too > prescriptive just gets in the way of attracting good contributions. This is just basic email etiquette :-) But, it's very annoying when you look at badly formatted subjects, in "git log --oneline" for example, it is very obvious there (and long subjects are problematic there as well btw). Wrt balance: yes, that is one reason why I do not think we should require all the markup stuff. > >>+<p>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. > > > >All non-trivial series, yeah. > > > >Maybe we should mention how v2 etc. of patch series should show what is > >changed? If there is a good standard practice for that at all :-) > > Dunno. I think that belongs primarily in the v2 0/n mail. It's not, > after all, something that needs to be kept once the patches are applied. Sure. Ah, we could recommend that then, to make it clear in the vM 0/N of some series which patches changed how. My point is that it is a waste of time to everyone if a reviewer has to drag through everything every time; this is double true with git, it is easy to send updated versions of patch sets often. Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-01-21 15:04 ` [PATCH, v2] wwwdocs: e-mail subject lines for contributions Richard Earnshaw (lists) 2020-01-21 15:10 ` Jakub Jelinek 2020-01-21 20:17 ` Segher Boessenkool @ 2020-01-22 19:15 ` Richard Earnshaw (lists) 2020-02-03 11:41 ` Richard Earnshaw (lists) 2 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-01-22 19:15 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: gcc-patches, GCC Development [-- Attachment #1: Type: text/plain, Size: 896 bytes --] [updated based on v2 discussions] This patch proposes some new (additional) rules for email subject lines when contributing to GCC. The goal is to make sure that, as far as possible, the subject for a patch will form a good summary when the message is committed to the repository if applied with 'git am'. Where possible, I've tried to align these rules with those already in use for glibc, so that the differences are minimal and only where necessary. Some things that differ from existing practice (at least by some people) are: - Use '<topic>:' rather than '[<topic>]' - This is more git friendly and works with 'git am'. - Put bug numbers at the end of the line rather than the beginning. - The bug number is useful, but not as useful as the brief summary. Also, use the shortened form, as the topic part is more usefully conveyed in the proper topic field (see above). [-- Attachment #2: contrib.patch --] [-- Type: text/x-patch, Size: 6900 bytes --] diff --git a/htdocs/contribute.html b/htdocs/contribute.html index 042ff069..558bae29 100644 --- a/htdocs/contribute.html +++ b/htdocs/contribute.html @@ -249,13 +249,143 @@ that ChangeLog entries may be included as part of the patch and diffs representing new files may be omitted, especially if large, since they can be accessed directly from the repository.)</p> +<h3>E-mail subject lines</h3> + +<p>Your contribution e-mail subject line will become the first line of +the commit message for your patch.</p> + +<p>A high-quality e-mail subject line for a contribution contains the +following elements:</p> + +<ul> + <li>A classifier</li> + <li>Component tags</li> + <li>An optional series identifier</li> + <li>A brief summary</li> + <li>An optional bug number</li> +</ul> + +<p>The entire line (excluding the classifier) should not exceed 75 +characters.</p> + +<h4>Classifier</h4> + +<p>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 (v<i>N</i>) and +a series marker (<i>N/M</i>). Examples are:</p> + +<ul> + <li><code>[PATCH]</code> - a single patch</li> + <li><code>[PATCH v2]</code> - the second version of a single patch</li> + <li><code>[PATCH 3/7]</code> - the third patch in a series of seven + patches</li> + <li><code>[RFC]</code> - a point of discussion, may contain a patch</li> + <li><code>[COMMITTED]</code> - a patch that has already been committed.</li> +</ul> + +<h4>Component tags</h4> + +<p>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,</p> + +<ul> + <li><code>libstdc++:</code></li> + <li><code>combine:</code></li> + <li><code>vax: testsuite:</code></li> +</ul> + +<p>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 <i>component/sub-component:</i>.</p> + +<h4>Series identifier</h4> + +<p>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 <i>short</i> string that identifies the series (it is common to all +patches) and should be followed by a single dash surrounded by white +space.</p> + +<h4>A Very Brief summary</h4> + +<p>The brief summary encapsulates in a few words the intent of the +change. For example: <code>cleanup check_field_decls</code>. +Although, very short, the summary should be distinct so that it will +not be confused with other patches.</p> + +<h4>Bug number</h4> + +<p>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 <code>[PR<i>nnnnn</i>]</code> 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 +(<code>PR <component>/<i>nnnnn</i></code>) within the body of +the commit message so that Bugzilla will correctly notice the +commit. If your patch relates to two bugs, then write +<code>[PR<i>nnnnn</i>, PR<i>mmmmm</i>]</code>. 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.</p> + +<p>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.</p> + +<h4>Other messages</h4> + +<p>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: <code>[PATCH +0/7]</code>. 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.</p> + +<p>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/<i>nnn</i>) 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.</p> + +<h4>Examples</h4> + +<p>Here are some complete examples, based on real commits to GCC.</p> + +<ul> + <li><code>[COMMITTED] libstdc++: Fix freestanding build [PR92376]</code></li> + <li><code>[PATCH 1/6] analyzer: Fix tests for UNKNOWN_LOCATION</code></li> + <li><code>[RFC] doc: Note that some warnings depend on optimizations [PR92757]</code></li> + <li><code>[COMMITTED] c++: coroutines - Initial implementation</code></li> + <li><code>[PATCH v2] wwwdocs: E-mail subject lines for contributions</code></li> +</ul> + <h3>Pinging patches, Getting patches applied</h3> <p>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.</p> +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.</p> <p>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 ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-01-22 19:15 ` [PATCH, v3] " Richard Earnshaw (lists) @ 2020-02-03 11:41 ` Richard Earnshaw (lists) 2020-02-03 11:54 ` Alexander Monakov 2020-02-27 13:38 ` Nathan Sidwell 0 siblings, 2 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 11:41 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: gcc-patches, GCC Development On 22/01/2020 17:45, Richard Earnshaw (lists) wrote: > > [updated based on v2 discussions] > > This patch proposes some new (additional) rules for email subject lines > when contributing to GCC. The goal is to make sure that, as far as > possible, the subject for a patch will form a good summary when the > message is committed to the repository if applied with 'git am'. Where > possible, I've tried to align these rules with those already in > use for glibc, so that the differences are minimal and only where > necessary. > > Some things that differ from existing practice (at least by some people) > are: > > - Use '<topic>:' rather than '[<topic>]' >  - This is more git friendly and works with 'git am'. > - Put bug numbers at the end of the line rather than the beginning. >  - The bug number is useful, but not as useful as the brief summary. >    Also, use the shortened form, as the topic part is more usefully >    conveyed in the proper topic field (see above). I've not seen any follow-up to this version. Should we go ahead and adopt this? R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 11:41 ` Richard Earnshaw (lists) @ 2020-02-03 11:54 ` Alexander Monakov 2020-02-03 11:59 ` Richard Earnshaw (lists) 2020-02-03 13:54 ` Segher Boessenkool 2020-02-27 13:38 ` Nathan Sidwell 1 sibling, 2 replies; 53+ messages in thread From: Alexander Monakov @ 2020-02-03 11:54 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches, GCC Development On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > I've not seen any follow-up to this version. Should we go ahead and adopt > this? Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED? Spelling this with all-caps seems like a recent thing on gcc-patches, before everyone used the lowercase version, which makes more sense (no need to shout about the thing that didn't need any discussion before applying the patch). Also, while tools like 'git format-patch' will automatically put [PATCH] in the subject, for '[COMMITTED]' it will be the human typing that out, and it makes little sense to require people to meticulously type that out in caps. Especially when the previous practice was opposite. Thanks. Alexander ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 11:54 ` Alexander Monakov @ 2020-02-03 11:59 ` Richard Earnshaw (lists) 2020-02-03 12:51 ` Alexander Monakov 2020-02-03 13:54 ` Segher Boessenkool 1 sibling, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 11:59 UTC (permalink / raw) To: Alexander Monakov; +Cc: Gerald Pfeifer, gcc-patches, GCC Development On 03/02/2020 11:54, Alexander Monakov wrote: > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > >> I've not seen any follow-up to this version. Should we go ahead and adopt >> this? > > Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED? > Spelling this with all-caps seems like a recent thing on gcc-patches, before > everyone used the lowercase version, which makes more sense (no need to shout > about the thing that didn't need any discussion before applying the patch). > > Also, while tools like 'git format-patch' will automatically put [PATCH] in > the subject, for '[COMMITTED]' it will be the human typing that out, and > it makes little sense to require people to meticulously type that out in caps. > Especially when the previous practice was opposite. > > Thanks. > Alexander > Upper case is what glibc has, though it appears that it's a rule that is not strictly followed. If we change it, then it becomes another friction point between developer groups. Personally, I'd leave it as is, then turn a blind eye to such minor non-conformance. Quite frankly, then bit that matters most is what follows that, since that is what gets written into the git commit message. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 11:59 ` Richard Earnshaw (lists) @ 2020-02-03 12:51 ` Alexander Monakov 2020-02-03 14:11 ` Jason Merrill 0 siblings, 1 reply; 53+ messages in thread From: Alexander Monakov @ 2020-02-03 12:51 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches, GCC Development On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > Upper case is what glibc has, though it appears that it's a rule that is not > strictly followed. If we change it, then it becomes another friction point > between developer groups. Personally, I'd leave it as is, then turn a blind > eye to such minor non-conformance. In that case can we simply say that both 'committed' and 'COMMITTED' are okay, if we know glibc doesn't follow that rule and anticipate we will not follow it either? Thanks. Alexander ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 12:51 ` Alexander Monakov @ 2020-02-03 14:11 ` Jason Merrill 2020-02-03 15:13 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Jason Merrill @ 2020-02-03 14:11 UTC (permalink / raw) To: Alexander Monakov Cc: Richard Earnshaw (lists), Gerald Pfeifer, gcc-patches List, GCC Development On Mon, Feb 3, 2020 at 7:57 AM Alexander Monakov <amonakov@ispras.ru> wrote: > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > > > Upper case is what glibc has, though it appears that it's a rule that is > not > > strictly followed. If we change it, then it becomes another friction > point > > between developer groups. Personally, I'd leave it as is, then turn a > blind > > eye to such minor non-conformance. > > In that case can we simply say that both 'committed' and 'COMMITTED' are > okay, > if we know glibc doesn't follow that rule and anticipate we will not follow > it either? > And perhaps something shorter? "committed" is a long word. [PUSHED]? Jason ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:11 ` Jason Merrill @ 2020-02-03 15:13 ` Richard Earnshaw (lists) 2020-02-03 15:15 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 15:13 UTC (permalink / raw) To: Jason Merrill, Alexander Monakov Cc: Gerald Pfeifer, gcc-patches List, GCC Development On 03/02/2020 14:10, Jason Merrill wrote: > On Mon, Feb 3, 2020 at 7:57 AM Alexander Monakov <amonakov@ispras.ru> wrote: > >> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: >> >>> Upper case is what glibc has, though it appears that it's a rule that is >> not >>> strictly followed. If we change it, then it becomes another friction >> point >>> between developer groups. Personally, I'd leave it as is, then turn a >> blind >>> eye to such minor non-conformance. >> >> In that case can we simply say that both 'committed' and 'COMMITTED' are >> okay, >> if we know glibc doesn't follow that rule and anticipate we will not follow >> it either? >> > > And perhaps something shorter? "committed" is a long word. [PUSHED]? > > Jason > "Committed" is the accepted term in glibc. If we insist on something different, then that becomes a friction point. On the other hand, I really don't care personally as long as the meaning is clear. I'd be happy with the super-set of all of these, since it only appears in email messages, not the final commit. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 15:13 ` Richard Earnshaw (lists) @ 2020-02-03 15:15 ` Richard Earnshaw (lists) 0 siblings, 0 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 15:15 UTC (permalink / raw) To: Jason Merrill, Alexander Monakov Cc: Gerald Pfeifer, gcc-patches List, GCC Development On 03/02/2020 15:13, Richard Earnshaw (lists) wrote: > On 03/02/2020 14:10, Jason Merrill wrote: >> On Mon, Feb 3, 2020 at 7:57 AM Alexander Monakov <amonakov@ispras.ru> >> wrote: >> >>> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: >>> >>>> Upper case is what glibc has, though it appears that it's a rule >>>> that is >>> not >>>> strictly followed. If we change it, then it becomes another friction >>> point >>>> between developer groups. Personally, I'd leave it as is, then turn a >>> blind >>>> eye to such minor non-conformance. >>> >>> In that case can we simply say that both 'committed' and 'COMMITTED' are >>> okay, >>> if we know glibc doesn't follow that rule and anticipate we will not >>> follow >>> it either? >>> >> >> And perhaps something shorter? "committed" is a long word. [PUSHED]? >> >> Jason >> > > "Committed" is the accepted term in glibc. If we insist on something > different, then that becomes a friction point. > "COMMITTED", not "Committed". > On the other hand, I really don't care personally as long as the meaning > is clear. I'd be happy with the super-set of all of these, since it > only appears in email messages, not the final commit. > > R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 11:54 ` Alexander Monakov 2020-02-03 11:59 ` Richard Earnshaw (lists) @ 2020-02-03 13:54 ` Segher Boessenkool 2020-02-03 14:00 ` Richard Earnshaw (lists) 1 sibling, 1 reply; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 13:54 UTC (permalink / raw) To: Alexander Monakov Cc: Richard Earnshaw (lists), Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 02:54:05PM +0300, Alexander Monakov wrote: > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > > > I've not seen any follow-up to this version. Should we go ahead and adopt > > this? > > Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED? > Spelling this with all-caps seems like a recent thing on gcc-patches, before > everyone used the lowercase version, which makes more sense (no need to shout > about the thing that didn't need any discussion before applying the patch). Lower case certainly makes more sense. None of this are *rules*. We should not pretend they are. An email subject should be useful to what the receivers of that email use it for: see if it very interesting to them, see if it probably not interesting to them: that's the "smth: " at the start, and the PR number at the end, and of course the actual subject itself, so we should not put in too much fluff in the subject, there needs to be room left (in the less than fifty chars total) for an actual subject :-) (The example in the patch does not capitalise the subject line, btw. It should.) Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 13:54 ` Segher Boessenkool @ 2020-02-03 14:00 ` Richard Earnshaw (lists) 2020-02-03 14:13 ` Jonathan Wakely ` (4 more replies) 0 siblings, 5 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 14:00 UTC (permalink / raw) To: Segher Boessenkool, Alexander Monakov Cc: Gerald Pfeifer, gcc-patches, GCC Development On 03/02/2020 13:54, Segher Boessenkool wrote: > On Mon, Feb 03, 2020 at 02:54:05PM +0300, Alexander Monakov wrote: >> On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: >> >>> I've not seen any follow-up to this version. Should we go ahead and adopt >>> this? >> >> Can we please go with 'committed' (lowercase) rather than all-caps COMMITTED? >> Spelling this with all-caps seems like a recent thing on gcc-patches, before >> everyone used the lowercase version, which makes more sense (no need to shout >> about the thing that didn't need any discussion before applying the patch). > > Lower case certainly makes more sense. > > None of this are *rules*. We should not pretend they are. An email > subject should be useful to what the receivers of that email use it for: > see if it very interesting to them, see if it probably not interesting > to them: that's the "smth: " at the start, and the PR number at the end, > and of course the actual subject itself, so we should not put in too > much fluff in the subject, there needs to be room left (in the less than > fifty chars total) for an actual subject :-) > > (The example in the patch does not capitalise the subject line, btw. > It should.) > > > Segher > Where does your '50 chars' limit come from? It's not in the glibc text, and it's not in the linux kernel text either. AFAICT this is your invention and you seem to be the only person proposing it. I think the linux rule (the whole line, not including the parts that are removed on commit, should not exceed 75 characters) is far more sensible - which is why this draft states this. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:00 ` Richard Earnshaw (lists) @ 2020-02-03 14:13 ` Jonathan Wakely 2020-02-03 15:05 ` Richard Earnshaw (lists) 2020-02-03 17:17 ` Segher Boessenkool ` (3 subsequent siblings) 4 siblings, 1 reply; 53+ messages in thread From: Jonathan Wakely @ 2020-02-03 14:13 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, 3 Feb 2020 at 14:00, Richard Earnshaw (lists) wrote: > Where does your '50 chars' limit come from? It's not in the glibc text, > and it's not in the linux kernel text either. AFAICT this is your > invention and you seem to be the only person proposing it. It's a fairly well established convention, e.g. https://chris.beams.io/posts/git-commit/ and it's what Github suggests (and whines if you go past it). > I think the linux rule (the whole line, not including the parts that are > removed on commit, should not exceed 75 characters) is far more sensible > - which is why this draft states this. I'm OK with that. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:13 ` Jonathan Wakely @ 2020-02-03 15:05 ` Richard Earnshaw (lists) 2020-02-03 16:12 ` Andrew Clayton 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 15:05 UTC (permalink / raw) To: Jonathan Wakely Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On 03/02/2020 14:13, Jonathan Wakely wrote: > On Mon, 3 Feb 2020 at 14:00, Richard Earnshaw (lists) wrote: >> Where does your '50 chars' limit come from? It's not in the glibc text, >> and it's not in the linux kernel text either. AFAICT this is your >> invention and you seem to be the only person proposing it. > > It's a fairly well established convention, e.g. > https://chris.beams.io/posts/git-commit/ and it's what Github suggests > (and whines if you go past it). > That suggest it as a limit for everything. If you have a tag and a bug number then then that would leave very little for the real part of the summary and would likely lead to something meaningless or incomprehensible in the remaining characters. That might be OK for small projects, but for something the size of gcc, I think keeping the extra flexibility is useful. >> I think the linux rule (the whole line, not including the parts that are >> removed on commit, should not exceed 75 characters) is far more sensible >> - which is why this draft states this. > > I'm OK with that. > OK, thanks. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 15:05 ` Richard Earnshaw (lists) @ 2020-02-03 16:12 ` Andrew Clayton 0 siblings, 0 replies; 53+ messages in thread From: Andrew Clayton @ 2020-02-03 16:12 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, 3 Feb 2020 15:04:57 +0000 "Richard Earnshaw (lists)" <Richard.Earnshaw@arm.com> wrote: > On 03/02/2020 14:13, Jonathan Wakely wrote: > > On Mon, 3 Feb 2020 at 14:00, Richard Earnshaw (lists) wrote: > >> Where does your '50 chars' limit come from? It's not in the glibc text, > >> and it's not in the linux kernel text either. AFAICT this is your > >> invention and you seem to be the only person proposing it. > > > > It's a fairly well established convention, e.g. > > https://chris.beams.io/posts/git-commit/ and it's what Github suggests > > (and whines if you go past it). > > > > That suggest it as a limit for everything. If you have a tag and a bug > number then then that would leave very little for the real part of the > summary and would likely lead to something meaningless or > incomprehensible in the remaining characters. That might be OK for > small projects, but for something the size of gcc, I think keeping the > extra flexibility is useful. Hopefully I've been following this discussion properly. It's important to clarify that there are two *limits* in play here. The subject should generally be kept to 50 chars or less, This is because the subject is displayed in the output of commands like 'git log --oneline' and 'git shortlog' which indents more than git log. Then the message body should wrap after 72-75 chars, again as the output of the likes of 'git log' indent the message by 4 chars. Using vim as the git commit message editor, vim will show you when your subject line is over 50 chars and it wraps the message body after 72 chars. Cheers, Andrew ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:00 ` Richard Earnshaw (lists) 2020-02-03 14:13 ` Jonathan Wakely @ 2020-02-03 17:17 ` Segher Boessenkool 2020-02-03 17:19 ` Segher Boessenkool ` (2 subsequent siblings) 4 siblings, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 17:17 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 01:59:58PM +0000, Richard Earnshaw (lists) wrote: > On 03/02/2020 13:54, Segher Boessenkool wrote: > >None of this are *rules*. We should not pretend they are. An email > >subject should be useful to what the receivers of that email use it for: > >see if it very interesting to them, see if it probably not interesting > >to them: that's the "smth: " at the start, and the PR number at the end, > >and of course the actual subject itself, so we should not put in too > >much fluff in the subject, there needs to be room left (in the less than > >fifty chars total) for an actual subject :-) > > > >(The example in the patch does not capitalise the subject line, btw. > >It should.) > > Where does your '50 chars' limit come from? It's not in the glibc text, > and it's not in the linux kernel text either. AFAICT this is your > invention and you seem to be the only person proposing it. Ha, no. It seems it originally is from https://github.com/git/git/commit/927a503cd07718ea0f700052043f383253904a56 and it has been part of "man git commit" since https://github.com/git/git/commit/936f32d3de468db8daf853155ddd5c6b191af60c (2006 and 2007, resp.) Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:00 ` Richard Earnshaw (lists) 2020-02-03 14:13 ` Jonathan Wakely 2020-02-03 17:17 ` Segher Boessenkool @ 2020-02-03 17:19 ` Segher Boessenkool 2020-02-03 17:31 ` Michael Matz 2020-02-03 17:34 ` Segher Boessenkool 4 siblings, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 17:19 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 01:59:58PM +0000, Richard Earnshaw (lists) wrote: > On 03/02/2020 13:54, Segher Boessenkool wrote: > >None of this are *rules*. We should not pretend they are. An email > >subject should be useful to what the receivers of that email use it for: > >see if it very interesting to them, see if it probably not interesting > >to them: that's the "smth: " at the start, and the PR number at the end, > >and of course the actual subject itself, so we should not put in too > >much fluff in the subject, there needs to be room left (in the less than > >fifty chars total) for an actual subject :-) > > > >(The example in the patch does not capitalise the subject line, btw. > >It should.) > > Where does your '50 chars' limit come from? It's not in the glibc text, > and it's not in the linux kernel text either. AFAICT this is your > invention and you seem to be the only person proposing it. > > I think the linux rule (the whole line, not including the parts that are > removed on commit, should not exceed 75 characters) is far more sensible > - which is why this draft states this. Oh, and it's not a limit, just a strong recommendation. Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:00 ` Richard Earnshaw (lists) ` (2 preceding siblings ...) 2020-02-03 17:19 ` Segher Boessenkool @ 2020-02-03 17:31 ` Michael Matz 2020-02-03 17:36 ` Richard Earnshaw (lists) 2020-02-03 17:34 ` Segher Boessenkool 4 siblings, 1 reply; 53+ messages in thread From: Michael Matz @ 2020-02-03 17:31 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development Hello, On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > Where does your '50 chars' limit come from? It's not in the glibc text, > and it's not in the linux kernel text either. AFAICT this is your > invention and you seem to be the only person proposing it. Nope, it's fairly common, so much so that it's included in the "commonly accepted rules" that googling for "git subject lines" gives you (as a snippet glimpse from some website), and that vim changes color when spilling over 50 chars. I actually thought it was universal and obvious until this thread (which is why I admittedly only did the above google right before writing this mail). For the rationale: 'git log --oneline' with hash and author or date should fit the usual 72 char limit. (An 11-character hash plus space alone would come out as 60 chars for the subject) That's also the reason why some people (certainly me) are nervous about or dislike all the "tags" in the subject line. E.g. what essential information (and subjects are for essential info, right?) is "[committed]" (or, even worse "[patch]") supposed to transport? If the rest of the subject doesn't interest me, I don't care if something was committed or not; if it _does_ interest me, then I'm going to look at the mail/patch either way, if committed or not; at which point the info if the author required review or has already committed it could be gives in the body as well. Similar for some other metainfo tags. (The "subsystem:" is good, though). And if we must have these tags, then why not at least short ones? Why isn't "[cmt]" or something enough? There will be very few tags, so they become mnemonic pretty much immediately. What becomes clearer when writing "[patch v2 1/13]" in comparison to "[v2 1/13]"? Ciao, Michael. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:31 ` Michael Matz @ 2020-02-03 17:36 ` Richard Earnshaw (lists) 2020-02-03 17:49 ` Michael Matz 0 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 17:36 UTC (permalink / raw) To: Michael Matz Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On 03/02/2020 17:31, Michael Matz wrote: > Hello, > > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > >> Where does your '50 chars' limit come from? It's not in the glibc text, >> and it's not in the linux kernel text either. AFAICT this is your >> invention and you seem to be the only person proposing it. > > Nope, it's fairly common, so much so that it's included in the "commonly > accepted rules" that googling for "git subject lines" gives you (as a > snippet glimpse from some website), and that vim changes color when > spilling over 50 chars. I actually thought it was universal and obvious > until this thread (which is why I admittedly only did the above google > right before writing this mail). For the rationale: 'git log --oneline' > with hash and author or date should fit the usual 72 char limit. (An > 11-character hash plus space alone would come out as 60 chars for the > subject) > > That's also the reason why some people (certainly me) are nervous about or > dislike all the "tags" in the subject line. E.g. what essential > information (and subjects are for essential info, right?) is "[committed]" > (or, even worse "[patch]") supposed to transport? If the rest of the > subject doesn't interest me, I don't care if something was committed or > not; if it _does_ interest me, then I'm going to look at the mail/patch > either way, if committed or not; at which point the info if the author > required review or has already committed it could be gives in the body as > well. Similar for some other metainfo tags. (The "subsystem:" is good, > though). > > And if we must have these tags, then why not at least short ones? Why > isn't "[cmt]" or something enough? There will be very few tags, so they > become mnemonic pretty much immediately. What becomes clearer when > writing "[patch v2 1/13]" in comparison to "[v2 1/13]"? > The idea is that the [...] part is NOT part of the commit, only part of the email. 'git am' would strip leading [...] automatically unless you've configured, or asked git to do otherwise. So that leading part is not counted for the length calculation. R. > > Ciao, > Michael. > ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:36 ` Richard Earnshaw (lists) @ 2020-02-03 17:49 ` Michael Matz 2020-02-03 17:54 ` Richard Earnshaw (lists) ` (2 more replies) 0 siblings, 3 replies; 53+ messages in thread From: Michael Matz @ 2020-02-03 17:49 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development Hi, On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > The idea is that the [...] part is NOT part of the commit, only part of > the email. I understand that, but the subject line of this thread says "e-mail subject lines", so I thought we were talking about, well, exactly that; and I see no value of these tags in e-mails either. (They might have a low but non-zero value for projects that use a single mailing list for patches and generic discussion, but we are not such project) Basically: if they are deemed to clutter the git log for whatever reason, then there must be a very good argument for why they not also clutter e-mail subject lines, but instead are essential to have there, but not in the log. > 'git am' would strip leading [...] automatically unless > you've configured, or asked git to do otherwise. So that leading part > is not counted for the length calculation. There's still e-mail netiquette which also should be obeyed, or at least not contradicted by git netiquette. Ciao, Michael. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:49 ` Michael Matz @ 2020-02-03 17:54 ` Richard Earnshaw (lists) 2020-02-03 18:20 ` Michael Matz 2020-02-03 17:54 ` Jakub Jelinek 2020-02-03 18:03 ` Joseph Myers 2 siblings, 1 reply; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-02-03 17:54 UTC (permalink / raw) To: Michael Matz Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On 03/02/2020 17:48, Michael Matz wrote: > Hi, > > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > >> The idea is that the [...] part is NOT part of the commit, only part of >> the email. > > I understand that, but the subject line of this thread says "e-mail > subject lines", so I thought we were talking about, well, exactly that; > and I see no value of these tags in e-mails either. > > (They might have a low but non-zero value for projects that use > a single mailing list for patches and generic discussion, but we are not > such project) > > Basically: if they are deemed to clutter the git log for whatever reason, > then there must be a very good argument for why they not also clutter > e-mail subject lines, but instead are essential to have there, > but not in the log. > Well, I'd review a patch differently depending on whether or not it was already committed, a patch requiring review or an RFC looking for more general comments, so I *do* think such an email prefix is useful. >> 'git am' would strip leading [...] automatically unless >> you've configured, or asked git to do otherwise. So that leading part >> is not counted for the length calculation. > > There's still e-mail netiquette which also should be obeyed, or at least > not contradicted by git netiquette. > The 50 char limit seems to come from wanting git log --oneline to not wrap in an 80 column terminal. Whilst laudable, I'm not sure that such a limit doesn't become too restrictive and then lead to hard-to-understand summaries. R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:54 ` Richard Earnshaw (lists) @ 2020-02-03 18:20 ` Michael Matz 2020-02-03 19:48 ` Segher Boessenkool 0 siblings, 1 reply; 53+ messages in thread From: Michael Matz @ 2020-02-03 18:20 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development Hello, On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > Well, I'd review a patch differently depending on whether or not it was > already committed, a patch requiring review or an RFC looking for more > general comments, so I *do* think such an email prefix is useful. As I said: a very good argument must be made; it might be that rfc falls into the useful-tag category. > >> 'git am' would strip leading [...] automatically unless > >> you've configured, or asked git to do otherwise. So that leading part > >> is not counted for the length calculation. > > > > There's still e-mail netiquette which also should be obeyed, or at least > > not contradicted by git netiquette. > > The 50 char limit seems to come from wanting git log --oneline to not wrap in > an 80 column terminal. Whilst laudable, I'm not sure that such a limit > doesn't become too restrictive and then lead to hard-to-understand summaries. In my experience hard-to-understand summaries are more related to people writing them than to length, IOW, I fear a larger limit like 72 characters won't help that. And, as Segher put it, we aren't really talking about limits, only about suggestions, if you _really_ have to mention that 40-character function name in which you fixed something in your subject, then yeah, you'll go over the 50 chars. But as recommendation the 50 chars make more sense than the 72 chars, IMHO. Ciao, Michael. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 18:20 ` Michael Matz @ 2020-02-03 19:48 ` Segher Boessenkool 0 siblings, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 19:48 UTC (permalink / raw) To: Michael Matz Cc: Richard Earnshaw (lists), Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 06:20:20PM +0000, Michael Matz wrote: > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > > Well, I'd review a patch differently depending on whether or not it was > > already committed, a patch requiring review or an RFC looking for more > > general comments, so I *do* think such an email prefix is useful. > > As I said: a very good argument must be made; it might be that rfc falls > into the useful-tag category. Yes, "rfc" can be useful to know *before* reading the mail. > > The 50 char limit seems to come from wanting git log --oneline to not wrap in > > an 80 column terminal. Whilst laudable, I'm not sure that such a limit > > doesn't become too restrictive and then lead to hard-to-understand summaries. > > In my experience hard-to-understand summaries are more related to people > writing them than to length, IOW, I fear a larger limit like 72 characters > won't help that. Yup. If it helps, don't think of it as "summary", think of it as "title". Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:49 ` Michael Matz 2020-02-03 17:54 ` Richard Earnshaw (lists) @ 2020-02-03 17:54 ` Jakub Jelinek 2020-02-03 18:09 ` Michael Matz 2020-02-03 18:57 ` Segher Boessenkool 2020-02-03 18:03 ` Joseph Myers 2 siblings, 2 replies; 53+ messages in thread From: Jakub Jelinek @ 2020-02-03 17:54 UTC (permalink / raw) To: Michael Matz Cc: Richard Earnshaw (lists), Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 05:48:57PM +0000, Michael Matz wrote: > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > > > The idea is that the [...] part is NOT part of the commit, only part of > > the email. > > I understand that, but the subject line of this thread says "e-mail > subject lines", so I thought we were talking about, well, exactly that; > and I see no value of these tags in e-mails either. In email, they do carry information that is useful there, the distinction whether a patch has been committed already and doesn't need review from others, or whether it is a patch intended for patch review, or just a RFC patch that is not yet ready for review, but submitter is looking for some feedback. Jakub ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:54 ` Jakub Jelinek @ 2020-02-03 18:09 ` Michael Matz 2020-02-04 10:41 ` Andrew Stubbs 2020-02-03 18:57 ` Segher Boessenkool 1 sibling, 1 reply; 53+ messages in thread From: Michael Matz @ 2020-02-03 18:09 UTC (permalink / raw) To: Jakub Jelinek Cc: Richard Earnshaw (lists), Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development Hello, On Mon, 3 Feb 2020, Jakub Jelinek wrote: > > > The idea is that the [...] part is NOT part of the commit, only part of > > > the email. > > > > I understand that, but the subject line of this thread says "e-mail > > subject lines", so I thought we were talking about, well, exactly that; > > and I see no value of these tags in e-mails either. > > In email, they do carry information that is useful there, the distinction > whether a patch has been committed already and doesn't need review from > others, or whether it is a patch intended for patch review, or just a RFC > patch that is not yet ready for review, but submitter is looking for some > feedback. For tags like [cmt] or [rfc] I don't have much gripe, though I do think that info could be given in the body, and that e.g. in e-mail archives (where the tags are not removed automatically) they carry the same value as in git log, namely zero. But suggesting that using the subject line for tagging is recommended can lead to subjects like [PATCH][GCC][Foo][component] Fix foo component bootstrap failure in an e-mail directed to gcc-patches@gcc.gnu.org (from somewhen last year, where Foo/foo was an architecture; I'm really not trying to single out the author). That is, _none_ of the four tags carried any informational content. Ciao, Michael. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 18:09 ` Michael Matz @ 2020-02-04 10:41 ` Andrew Stubbs 0 siblings, 0 replies; 53+ messages in thread From: Andrew Stubbs @ 2020-02-04 10:41 UTC (permalink / raw) To: Michael Matz, Jakub Jelinek Cc: Richard Earnshaw (lists), Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On 03/02/2020 18:09, Michael Matz wrote: > But suggesting that using the subject line for tagging is recommended can > lead to subjects like > > [PATCH][GCC][Foo][component] Fix foo component bootstrap failure > > in an e-mail directed to gcc-patches@gcc.gnu.org (from somewhen last year, > where Foo/foo was an architecture; I'm really not trying to single out the > author). That is, _none_ of the four tags carried any informational > content. I partially disagree with this. Certainly there's pointless redundancy it this example, but I'd rather have the tags with a meaningful subject than a generic subject with no tags. gcc-patches is a high-volume list in which most of the content is outside my range of interest and/or understanding. If I stay on top of it then I can read all the subject lines, at least, and probably select a few threads to learn about something new, but if I let the list get away from me for even a short while then it's too much to handle. I do have filters set up to highlight subjects for which I should pay attention and if people are in the habit of tagging subjects then that becomes much more reliable. Conversely, the tags help me quickly decide what not to read. I see that some people are using a "[email tag] git tag: msg" format, and I quite like that. Andrew ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:54 ` Jakub Jelinek 2020-02-03 18:09 ` Michael Matz @ 2020-02-03 18:57 ` Segher Boessenkool 1 sibling, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 18:57 UTC (permalink / raw) To: Jakub Jelinek Cc: Michael Matz, Richard Earnshaw (lists), Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 06:54:05PM +0100, Jakub Jelinek wrote: > On Mon, Feb 03, 2020 at 05:48:57PM +0000, Michael Matz wrote: > > On Mon, 3 Feb 2020, Richard Earnshaw (lists) wrote: > > > > > The idea is that the [...] part is NOT part of the commit, only part of > > > the email. > > > > I understand that, but the subject line of this thread says "e-mail > > subject lines", so I thought we were talking about, well, exactly that; > > and I see no value of these tags in e-mails either. > > In email, they do carry information that is useful there, the distinction > whether a patch has been committed already and doesn't need review from > others, or whether it is a patch intended for patch review, or just a RFC > patch that is not yet ready for review, but submitter is looking for some > feedback. It's irrelevant whether a patch is committed or not whather it needs review, imnsho :-) "rfc" is useful, certainly. It makes clear that the sender would like some help, and/or that the subject might be controversial, both things that have more time pressure than most. Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 17:49 ` Michael Matz 2020-02-03 17:54 ` Richard Earnshaw (lists) 2020-02-03 17:54 ` Jakub Jelinek @ 2020-02-03 18:03 ` Joseph Myers 2 siblings, 0 replies; 53+ messages in thread From: Joseph Myers @ 2020-02-03 18:03 UTC (permalink / raw) To: Michael Matz Cc: Richard Earnshaw (lists), Segher Boessenkool, Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, 3 Feb 2020, Michael Matz wrote: > I understand that, but the subject line of this thread says "e-mail > subject lines", so I thought we were talking about, well, exactly that; > and I see no value of these tags in e-mails either. I agree that [PATCH] is not useful (and in general, anything in the subject line before the actual meaningful commit summary should be as short as possible). [RFC] might be useful, but not [PATCH]. -- Joseph S. Myers joseph@codesourcery.com ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 14:00 ` Richard Earnshaw (lists) ` (3 preceding siblings ...) 2020-02-03 17:31 ` Michael Matz @ 2020-02-03 17:34 ` Segher Boessenkool 4 siblings, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 17:34 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Alexander Monakov, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Feb 03, 2020 at 01:59:58PM +0000, Richard Earnshaw (lists) wrote: > I think the linux rule (the whole line, not including the parts that are > removed on commit, should not exceed 75 characters) is far more sensible > - which is why this draft states this. FWIW, on a slightly older kernel tree: $ git log --oneline --format=%s|awk '{print length}'|sort -n|uniq -c|sort -r -n|head -10 25059 50 24872 49 24563 47 24547 48 24261 51 24050 52 23773 53 23527 46 23231 54 22907 45 On git.git: $ git log --oneline --format=%s|awk '{print length}'|sort -n|uniq -c|sort -r -n|head -10 1694 50 1657 49 1649 44 1623 46 1621 48 1606 43 1579 45 1558 47 1544 51 1499 37 Sometimes longer subject lines are unavoidable. Most of the time they can be pretty easily avoided, and they hurt usability. It is okay to spend a few minutes on it, think of the thousands of people who will later read it. Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-03 11:41 ` Richard Earnshaw (lists) 2020-02-03 11:54 ` Alexander Monakov @ 2020-02-27 13:38 ` Nathan Sidwell 2020-03-02 13:01 ` Richard Earnshaw (lists) 1 sibling, 1 reply; 53+ messages in thread From: Nathan Sidwell @ 2020-02-27 13:38 UTC (permalink / raw) To: Richard Earnshaw (lists), Gerald Pfeifer; +Cc: gcc-patches, GCC Development On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote: > On 22/01/2020 17:45, Richard Earnshaw (lists) wrote: >> >> [updated based on v2 discussions] >> >> This patch proposes some new (additional) rules for email subject lines >> when contributing to GCC. The goal is to make sure that, as far as >> possible, the subject for a patch will form a good summary when the >> message is committed to the repository if applied with 'git am'. Where >> possible, I've tried to align these rules with those already in >> use for glibc, so that the differences are minimal and only where >> necessary. >> >> Some things that differ from existing practice (at least by some people) >> are: >> >> - Use '<topic>:' rather than '[<topic>]' >>   - This is more git friendly and works with 'git am'. >> - Put bug numbers at the end of the line rather than the beginning. >>   - The bug number is useful, but not as useful as the brief summary. >>     Also, use the shortened form, as the topic part is more usefully >>     conveyed in the proper topic field (see above). > > I've not seen any follow-up to this version. Should we go ahead and > adopt this? do it! do it! do it! do it! nathan -- Nathan Sidwell ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-02-27 13:38 ` Nathan Sidwell @ 2020-03-02 13:01 ` Richard Earnshaw (lists) 2020-03-02 13:35 ` Segher Boessenkool 2020-03-02 14:31 ` Nathan Sidwell 0 siblings, 2 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-03-02 13:01 UTC (permalink / raw) To: Nathan Sidwell, Gerald Pfeifer; +Cc: gcc-patches, GCC Development On 27/02/2020 13:37, Nathan Sidwell wrote: > On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote: >> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote: >>> >>> [updated based on v2 discussions] >>> >>> This patch proposes some new (additional) rules for email subject lines >>> when contributing to GCC. The goal is to make sure that, as far as >>> possible, the subject for a patch will form a good summary when the >>> message is committed to the repository if applied with 'git am'. Where >>> possible, I've tried to align these rules with those already in >>> use for glibc, so that the differences are minimal and only where >>> necessary. >>> >>> Some things that differ from existing practice (at least by some people) >>> are: >>> >>> - Use '<topic>:' rather than '[<topic>]' >>> - This is more git friendly and works with 'git am'. >>> - Put bug numbers at the end of the line rather than the beginning. >>> - The bug number is useful, but not as useful as the brief summary. >>> Also, use the shortened form, as the topic part is more usefully >>> conveyed in the proper topic field (see above). >> >> I've not seen any follow-up to this version. Should we go ahead and >> adopt this? > > do it! > > do it! do it! do it! > > nathan :-) I'd like to. But have we reached consensus? Seems that every time I produce a revised version of the text we end up in another round of bike shedding. (Is that a word?) R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-03-02 13:01 ` Richard Earnshaw (lists) @ 2020-03-02 13:35 ` Segher Boessenkool 2020-03-02 14:31 ` Nathan Sidwell 1 sibling, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-03-02 13:35 UTC (permalink / raw) To: Richard Earnshaw (lists) Cc: Nathan Sidwell, Gerald Pfeifer, gcc-patches, GCC Development On Mon, Mar 02, 2020 at 01:01:46PM +0000, Richard Earnshaw (lists) wrote: > I'd like to. But have we reached consensus? Seems that every time I > produce a revised version of the text we end up in another round of bike > shedding. (Is that a word?) It's called a "lap", but "criterium" would be more suitable here. Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-03-02 13:01 ` Richard Earnshaw (lists) 2020-03-02 13:35 ` Segher Boessenkool @ 2020-03-02 14:31 ` Nathan Sidwell 2020-03-02 14:41 ` Jonathan Wakely 1 sibling, 1 reply; 53+ messages in thread From: Nathan Sidwell @ 2020-03-02 14:31 UTC (permalink / raw) To: Richard Earnshaw (lists), Gerald Pfeifer; +Cc: gcc-patches, GCC Development On 3/2/20 8:01 AM, Richard Earnshaw (lists) wrote: > On 27/02/2020 13:37, Nathan Sidwell wrote: >> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote: >>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote: >>>> >>>> [updated based on v2 discussions] >>>> >>>> This patch proposes some new (additional) rules for email subject lines >>>> when contributing to GCC. The goal is to make sure that, as far as >>>> possible, the subject for a patch will form a good summary when the >>>> message is committed to the repository if applied with 'git am'. Where >>>> possible, I've tried to align these rules with those already in >>>> use for glibc, so that the differences are minimal and only where >>>> necessary. >>>> >>>> Some things that differ from existing practice (at least by some >>>> people) >>>> are: >>>> >>>> - Use '<topic>:' rather than '[<topic>]' >>>> - This is more git friendly and works with 'git am'. >>>> - Put bug numbers at the end of the line rather than the beginning. >>>> - The bug number is useful, but not as useful as the brief summary. >>>> Also, use the shortened form, as the topic part is more usefully >>>> conveyed in the proper topic field (see above). >>> >>> I've not seen any follow-up to this version. Should we go ahead and >>> adopt this? > I'd like to. But have we reached consensus? Seems that every time I > produce a revised version of the text we end up in another round of bike > shedding. (Is that a word?) I'm not sure I've seen a specific proposal following yours. Some suggestions for differences, with varying degrees of forcefulness. I still say go for it. nathan -- Nathan Sidwell ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-03-02 14:31 ` Nathan Sidwell @ 2020-03-02 14:41 ` Jonathan Wakely 2020-03-02 15:22 ` Richard Earnshaw (lists) 0 siblings, 1 reply; 53+ messages in thread From: Jonathan Wakely @ 2020-03-02 14:41 UTC (permalink / raw) To: Nathan Sidwell Cc: Richard Earnshaw (lists), Gerald Pfeifer, gcc-patches, GCC Development On Mon, 2 Mar 2020 at 14:31, Nathan Sidwell <nathan@acm.org> wrote: > > On 3/2/20 8:01 AM, Richard Earnshaw (lists) wrote: > > On 27/02/2020 13:37, Nathan Sidwell wrote: > >> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote: > >>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote: > >>>> > >>>> [updated based on v2 discussions] > >>>> > >>>> This patch proposes some new (additional) rules for email subject lines > >>>> when contributing to GCC. The goal is to make sure that, as far as > >>>> possible, the subject for a patch will form a good summary when the > >>>> message is committed to the repository if applied with 'git am'. Where > >>>> possible, I've tried to align these rules with those already in > >>>> use for glibc, so that the differences are minimal and only where > >>>> necessary. > >>>> > >>>> Some things that differ from existing practice (at least by some > >>>> people) > >>>> are: > >>>> > >>>> - Use '<topic>:' rather than '[<topic>]' > >>>> - This is more git friendly and works with 'git am'. > >>>> - Put bug numbers at the end of the line rather than the beginning. > >>>> - The bug number is useful, but not as useful as the brief summary. > >>>> Also, use the shortened form, as the topic part is more usefully > >>>> conveyed in the proper topic field (see above). > >>> > >>> I've not seen any follow-up to this version. Should we go ahead and > >>> adopt this? > > > I'd like to. But have we reached consensus? Seems that every time I > > produce a revised version of the text we end up in another round of bike > > shedding. (Is that a word?) > > I'm not sure I've seen a specific proposal following yours. Some > suggestions for differences, with varying degrees of forcefulness. I > still say go for it. Go for it. It's not like we're going to take away commit privs from people who use slight variations on the scheme. It's better to have a written policy that people should aim towards, and most people will follow in most cases. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [PATCH, v3] wwwdocs: e-mail subject lines for contributions 2020-03-02 14:41 ` Jonathan Wakely @ 2020-03-02 15:22 ` Richard Earnshaw (lists) 0 siblings, 0 replies; 53+ messages in thread From: Richard Earnshaw (lists) @ 2020-03-02 15:22 UTC (permalink / raw) To: Jonathan Wakely, Nathan Sidwell Cc: Gerald Pfeifer, gcc-patches, GCC Development On 02/03/2020 14:41, Jonathan Wakely wrote: > On Mon, 2 Mar 2020 at 14:31, Nathan Sidwell <nathan@acm.org> wrote: >> >> On 3/2/20 8:01 AM, Richard Earnshaw (lists) wrote: >>> On 27/02/2020 13:37, Nathan Sidwell wrote: >>>> On 2/3/20 6:41 AM, Richard Earnshaw (lists) wrote: >>>>> On 22/01/2020 17:45, Richard Earnshaw (lists) wrote: >>>>>> >>>>>> [updated based on v2 discussions] >>>>>> >>>>>> This patch proposes some new (additional) rules for email subject lines >>>>>> when contributing to GCC. The goal is to make sure that, as far as >>>>>> possible, the subject for a patch will form a good summary when the >>>>>> message is committed to the repository if applied with 'git am'. Where >>>>>> possible, I've tried to align these rules with those already in >>>>>> use for glibc, so that the differences are minimal and only where >>>>>> necessary. >>>>>> >>>>>> Some things that differ from existing practice (at least by some >>>>>> people) >>>>>> are: >>>>>> >>>>>> - Use '<topic>:' rather than '[<topic>]' >>>>>> - This is more git friendly and works with 'git am'. >>>>>> - Put bug numbers at the end of the line rather than the beginning. >>>>>> - The bug number is useful, but not as useful as the brief summary. >>>>>> Also, use the shortened form, as the topic part is more usefully >>>>>> conveyed in the proper topic field (see above). >>>>> >>>>> I've not seen any follow-up to this version. Should we go ahead and >>>>> adopt this? >> >>> I'd like to. But have we reached consensus? Seems that every time I >>> produce a revised version of the text we end up in another round of bike >>> shedding. (Is that a word?) >> >> I'm not sure I've seen a specific proposal following yours. Some >> suggestions for differences, with varying degrees of forcefulness. I >> still say go for it. > > Go for it. > > It's not like we're going to take away commit privs from people who > use slight variations on the scheme. It's better to have a written > policy that people should aim towards, and most people will follow in > most cases. > OK, pushed. Folk can, of course, now propose changes to the text as it stands... R. ^ permalink raw reply [flat|nested] 53+ messages in thread
* Re: [wwwdocs] Updates to contribute.html for git-friendly posting rules 2020-01-20 11:54 ` Richard Earnshaw (lists) 2020-01-21 15:04 ` [PATCH, v2] wwwdocs: e-mail subject lines for contributions Richard Earnshaw (lists) @ 2020-02-03 15:34 ` Segher Boessenkool 1 sibling, 0 replies; 53+ messages in thread From: Segher Boessenkool @ 2020-02-03 15:34 UTC (permalink / raw) To: Richard Earnshaw (lists); +Cc: Gerald Pfeifer, gcc-patches (Old thread, first time I see it though): On Mon, Jan 20, 2020 at 11:45:28AM +0000, Richard Earnshaw (lists) wrote: > The more we make the process lightweight for contributors, the more work > we make for maintainers. If the contribution is sent correctly, then > ideally, the patch can be applied with just 'git am' by the maintainer. Almost always the maintainer will want to do "git am" followed by "git commit --amend" *anyway*. It helps if people follow the same format often, but making this a stringent requirement, even before we have experience with it, is just wrong, and does not help anyway. Segher ^ permalink raw reply [flat|nested] 53+ messages in thread
end of thread, other threads:[~2020-03-02 15:22 UTC | newest] Thread overview: 53+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-01-09 10:43 [wwwdocs] Updates to contribute.html for git-friendly posting rules Richard Earnshaw (lists) 2020-01-19 14:47 ` Gerald Pfeifer 2020-01-20 11:54 ` Richard Earnshaw (lists) 2020-01-21 15:04 ` [PATCH, v2] wwwdocs: e-mail subject lines for contributions Richard Earnshaw (lists) 2020-01-21 15:10 ` Jakub Jelinek 2020-01-21 15:34 ` Richard Earnshaw (lists) 2020-01-21 16:26 ` Jakub Jelinek 2020-01-21 16:26 ` Richard Earnshaw (lists) 2020-01-21 18:32 ` Jason Merrill 2020-01-21 19:09 ` Richard Earnshaw (lists) 2020-01-22 9:35 ` Jakub Jelinek 2020-01-22 10:00 ` Richard Earnshaw (lists) 2020-01-22 10:04 ` Jakub Jelinek 2020-01-22 16:27 ` Richard Sandiford 2020-01-22 17:02 ` Marek Polacek 2020-01-22 17:10 ` Richard Earnshaw (lists) 2020-01-21 20:17 ` Segher Boessenkool 2020-01-22 10:14 ` Richard Earnshaw (lists) 2020-01-22 14:06 ` Segher Boessenkool 2020-01-22 19:15 ` [PATCH, v3] " Richard Earnshaw (lists) 2020-02-03 11:41 ` Richard Earnshaw (lists) 2020-02-03 11:54 ` Alexander Monakov 2020-02-03 11:59 ` Richard Earnshaw (lists) 2020-02-03 12:51 ` Alexander Monakov 2020-02-03 14:11 ` Jason Merrill 2020-02-03 15:13 ` Richard Earnshaw (lists) 2020-02-03 15:15 ` Richard Earnshaw (lists) 2020-02-03 13:54 ` Segher Boessenkool 2020-02-03 14:00 ` Richard Earnshaw (lists) 2020-02-03 14:13 ` Jonathan Wakely 2020-02-03 15:05 ` Richard Earnshaw (lists) 2020-02-03 16:12 ` Andrew Clayton 2020-02-03 17:17 ` Segher Boessenkool 2020-02-03 17:19 ` Segher Boessenkool 2020-02-03 17:31 ` Michael Matz 2020-02-03 17:36 ` Richard Earnshaw (lists) 2020-02-03 17:49 ` Michael Matz 2020-02-03 17:54 ` Richard Earnshaw (lists) 2020-02-03 18:20 ` Michael Matz 2020-02-03 19:48 ` Segher Boessenkool 2020-02-03 17:54 ` Jakub Jelinek 2020-02-03 18:09 ` Michael Matz 2020-02-04 10:41 ` Andrew Stubbs 2020-02-03 18:57 ` Segher Boessenkool 2020-02-03 18:03 ` Joseph Myers 2020-02-03 17:34 ` Segher Boessenkool 2020-02-27 13:38 ` Nathan Sidwell 2020-03-02 13:01 ` Richard Earnshaw (lists) 2020-03-02 13:35 ` Segher Boessenkool 2020-03-02 14:31 ` Nathan Sidwell 2020-03-02 14:41 ` Jonathan Wakely 2020-03-02 15:22 ` Richard Earnshaw (lists) 2020-02-03 15:34 ` [wwwdocs] Updates to contribute.html for git-friendly posting rules Segher Boessenkool
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).