contribution checklist in the wiki

contribution checklist in the wiki

[Pedro Alves]

Guys,

I've created a new page in the wiki:

 http://sourceware.org/gdb/wiki/ContributionChecklist

This was heavily borrowed from glibc's own contribution checklist.
(I asked them if they were okay before doing it.)

At present, some of the info there duplicates what gdb/CONTRIBUTE
says (but in different wording).  I expect it to grow some, and I'd
rather keep it dynamic, without formal review/checking steps, which
IMO for this sort of think is a too heavy process.
I tailored the original text to make it fitter for gdb, but it's
possible/likely there are things that need more editing to make
it even fitter.

I've been noticing that I often find myself pointing at the same
little mistakes over different submissions.  E.g., pointing at
need to mention changes in NEWS.  As I notice these patterns, I'll
add them to the wiki.  I invite others to do the same.

Thanks,
-- 
Pedro Alves

Re: contribution checklist in the wiki

[Joel Brobecker]

> I've created a new page in the wiki:
> 
>  http://sourceware.org/gdb/wiki/ContributionChecklist
> 
> This was heavily borrowed from glibc's own contribution checklist.
> (I asked them if they were okay before doing it.)

I think it's a good idea. It's a little bit of a bummer that this
overlaps with CONTRIBUTE, because I think that the two documents
may diverge at some point.

Are we re-introducing the use of "patch" in email submissions?
Its use was unofficially discouraged I believe by Andrew Cagney,
who thought it was ambiguous (re: checked in or not?). I don't
mind, and it makes things simpler for git users, where PATCH
is the default for format-patch (which is used by send-email).

-- 
Joel

Re: contribution checklist in the wiki

[Hui Zhu]

Hi Pedro,

Thanks for you works.


I have a question about format of changelog:
2013-12-12  John Doe  <johndoe@some.email.address>

        PR gdb/9999

        * breakpoint.c (handle_some_event): Remove reference to<line
wrap at or before column 79>

If I remember is right, some people told me that there should not have
a empty line after "PR xxx".
And I checked the changelog, some of them have empty line and others don't have.

So does it need a empty line after "PR xxx"?


And I have another question is about [RFC].  Where should it be sent
to, gdb or gdb-patches?

Best,
Hui

On Sat, May 18, 2013 at 12:37 AM, Pedro Alves <palves@redhat.com> wrote:
> Guys,
>
> I've created a new page in the wiki:
>
>  http://sourceware.org/gdb/wiki/ContributionChecklist
>
> This was heavily borrowed from glibc's own contribution checklist.
> (I asked them if they were okay before doing it.)
>
> At present, some of the info there duplicates what gdb/CONTRIBUTE
> says (but in different wording).  I expect it to grow some, and I'd
> rather keep it dynamic, without formal review/checking steps, which
> IMO for this sort of think is a too heavy process.
> I tailored the original text to make it fitter for gdb, but it's
> possible/likely there are things that need more editing to make
> it even fitter.
>
> I've been noticing that I often find myself pointing at the same
> little mistakes over different submissions.  E.g., pointing at
> need to mention changes in NEWS.  As I notice these patterns, I'll
> add them to the wiki.  I invite others to do the same.
>
> Thanks,
> --
> Pedro Alves

Re: contribution checklist in the wiki

[Pedro Alves]

On 05/20/2013 11:21 AM, Hui Zhu wrote:
> Hi Pedro,
> 
> Thanks for you works.
> 
> 
> I have a question about format of changelog:
> 2013-12-12  John Doe  <johndoe@some.email.address>
> 
>         PR gdb/9999
> 
>         * breakpoint.c (handle_some_event): Remove reference to<line
> wrap at or before column 79>
> 
> If I remember is right, some people told me that there should not have
> a empty line after "PR xxx".
> And I checked the changelog, some of them have empty line and others don't have.
> 
> So does it need a empty line after "PR xxx"?
>

Thanks for raising this.  Doug expressed a preference for not having
the empty line too off-list.  I've now removed it from the wiki.

I've been adding it, as to me it visually indicated the different
areas - the "why/PR" area vs the "what" area.  Skimming through the
entries, it seems I was practically alone though.  :-)  I'll
stop adding it from here on.

> 
> And I have another question is about [RFC].  Where should it be sent
> to, gdb or gdb-patches?

Good question.  I assume you mean an RFC without a patch.

I think that boils down to, what are really gdb's and
gdb-patches's scopes.

Comparing to GCC, they have:

#1 gcc-help    - a list for end users of gcc.
#2 gcc         - a list for discussions on the development of gcc itself
#3 gcc-patches - a list for patches

We have gdb and gdb-patches, but no gdb-help.  (And bug-gdb@gnu.org, but
I think most gdb developers don't even subscribe it...)

I think gdb@ fills both roles of #1 and a little of #2 (wrt to user
visible changes), while gdb-patches@ the roles of both #2 and #3.  We tend to
leave RFC discussions of gdb's internals on the gdb-patches list, while RFC
proposals that might affect user interface changes, RSP changes, python API
extensions, etc. are best done on the gdb@ list, which has more end users
and frontend developers in it, who we'll want to hear input from.  Exactly
because gdb@ has many end users on it who don't care about gdb's internals
as long as it works, I personally (and I suspect that's what others feel too)
don't send RFCs about GDB internals there, but instead I'll send them to
gdb-patches@, because that's the list that has all the people that care
about gdb development.  This very thread being an example.

IOW,

 gdb-patches - the list all gdb developers should be on.

 gdb - the end list users are on.  Given there's no separate
 developer list, a list developers should be on too.

So in a nutshell, use some judgment, and choose where to send the RFC
to depending on the target audience, and on whether you're requesting comments
on large visible user interface changes (-> gdb@) or on gdb's
internals (-> gdb-patches@).

That's my view anyhow.  Might be others see things a little different.
If we reach some sort of consensus, we could put it somewhere in the wiki.

Thanks,
-- 
Pedro Alves

Re: contribution checklist in the wiki

[Pedro Alves]

On 05/20/2013 11:06 AM, Joel Brobecker wrote:
>> I've created a new page in the wiki:
>>
>>  http://sourceware.org/gdb/wiki/ContributionChecklist
>>
>> This was heavily borrowed from glibc's own contribution checklist.
>> (I asked them if they were okay before doing it.)
> 
> I think it's a good idea. It's a little bit of a bummer that this
> overlaps with CONTRIBUTE, because I think that the two documents
> may diverge at some point.

IMO, having CONTRIBUTE in the source tree is a bit questionable.
E.g., a user might write a patch against 7.5, and send it to the list,
using the guidelines from 7.5's CONTRIBUTE file.  But, that file might
well be outdated.  The guidelines that really matter are the one's gdb
developers follow at present, which may already be different from
the one's in 7.5's CONTRIBUTE.  I'd vote for migrating parts of the text
from CONTRIBUTE under "Submitting Patches" and "Supplemental information
for GDB" to the wiki.  But we can leave CONTRIBUTE alone until the
documents actually diverge.

> Are we re-introducing the use of "patch" in email submissions?
> Its use was unofficially discouraged I believe by Andrew Cagney,
> who thought it was ambiguous (re: checked in or not?). 

I didn't know it was discouraged.  [PATCH] never implied the
patch has been checked in to me.  For me, it's somewhat useful as
distinguishing the email from one about gdb internals (an RFC on some
internals, etc.) that doesn't come with a patch, as we often
see on gdb-patches@, despite the list's name.  I notice some of us
are using "FYI/fyi" or "COMMIT/commit" to explicitly indicate
"checked in".  I like that, and I've doing using COMMIT myself now.
Particularly, since I'm making the effort to put the rationale
for a patch in the cvs commit log, I find it better to write
"commit" in the subject line, rather than in the body of the
message (which ends up turned into the commit log entry),
as "Checked in." in the cvs/git log is useless and weird info.  :-)

I don't think we need to be super strict about these tags.
[PATCH]/[patch]/nothing is the same to me, as is
[RFC PATCH] vs [RFC][PATCH].  But I do think it's good to have
simple guidelines, mostly for people who are newcomers to the community.
Not listing many alternative choices to express the same is a feature, IMO.

This part of the wiki page was mostly still untouched compared to glibc's,
and comparing it to patches sent to libc-alpha@, we see that they aren't
strict with these either -- lots of patch submissions without "[PATCH]".

> I don't mind, and it makes things simpler for git users, where PATCH
> is the default for format-patch (which is used by send-email).

Yeah.  I've been using [PATCH] ever since I switched to git/stgit.  :-)

-- 
Pedro Alves

Re: contribution checklist in the wiki

[Doug Evans]

On Mon, May 20, 2013 at 7:44 AM, Pedro Alves <palves@redhat.com> wrote:
>> I have a question about format of changelog:
>> 2013-12-12  John Doe  <johndoe@some.email.address>
>>
>>         PR gdb/9999
>>
>>         * breakpoint.c (handle_some_event): Remove reference to<line
>> wrap at or before column 79>
>>
>> If I remember is right, some people told me that there should not have
>> a empty line after "PR xxx".
>> And I checked the changelog, some of them have empty line and others don't have.
>>
>> So does it need a empty line after "PR xxx"?
>>
>
> Thanks for raising this.  Doug expressed a preference for not having
> the empty line too off-list.  I've now removed it from the wiki.
>
> I've been adding it, as to me it visually indicated the different
> areas - the "why/PR" area vs the "what" area.  Skimming through the
> entries, it seems I was practically alone though.  :-)  I'll
> stop adding it from here on.

[for reference sake,]
For me when skimming a blank line means an unrelated patch.
[There's no requirement that each separate patch be preceded by a
name/timestamp line,
and emacs knows this.]
It's easy enough to pick out a new patch set starting with some
sentence or "PR 123"
instead of "* filename ...".

Re: contribution checklist in the wiki

[Joel Brobecker]

> IMO, having CONTRIBUTE in the source tree is a bit questionable.
> E.g., a user might write a patch against 7.5, and send it to the list,
> using the guidelines from 7.5's CONTRIBUTE file.  But, that file might
> well be outdated.  The guidelines that really matter are the one's gdb
> developers follow at present, which may already be different from
> the one's in 7.5's CONTRIBUTE.  I'd vote for migrating parts of the text
> from CONTRIBUTE under "Submitting Patches" and "Supplemental information
> for GDB" to the wiki.  But we can leave CONTRIBUTE alone until the
> documents actually diverge.

Transitioning the info from CONTRIBUTE to point to the wiki would
be OK for me.

> I don't think we need to be super strict about these tags.
> [PATCH]/[patch]/nothing is the same to me, as is
> [RFC PATCH] vs [RFC][PATCH].  But I do think it's good to have
> simple guidelines, mostly for people who are newcomers to the community.

Agreed.

Glad to see you put the patch description in the commit log, BTW!
I started doing that a while ago too, internally first, really liking
it, and then externally as well.

-- 
Joel

Re: contribution checklist in the wiki

[Pedro Alves]

On 05/21/2013 06:25 AM, Joel Brobecker wrote:

> Glad to see you put the patch description in the commit log, BTW!
> I started doing that a while ago too, internally first, really liking
> it, and then externally as well.

Now we just need to convince others.  :-)

As someone that has done _lots_ of archaeology on gdb's code,
including going further back beyond the cvs import, I've often
had trouble matching ChangeLogs to mailing list discussions, and
then often will still not find a clear rationale if I actually
find a match.  I can only wish people had been doing it too
"back then".

-- 
Pedro Alves

Re: contribution checklist in the wiki

[Joel Brobecker]

> Now we just need to convince others.  :-)

Next thing we know, we will be getting rid of ChangeLog files also :-)
(which I have done for the AdaCore version, btw)

> As someone that has done _lots_ of archaeology on gdb's code,
> including going further back beyond the cvs import, I've often
> had trouble matching ChangeLogs to mailing list discussions, and
> then often will still not find a clear rationale if I actually
> find a match.  I can only wish people had been doing it too
> "back then".

Same on my end - I constantly go back in history, both with the FSF
and AdaCore repositories, and found that they help tremendously.

-- 
Joel

Re: contribution checklist in the wiki

[Pedro Alves]

On 05/22/2013 07:29 AM, Joel Brobecker wrote:
>> Now we just need to convince others.  :-)
> 
> Next thing we know, we will be getting rid of ChangeLog files also :-)
> (which I have done for the AdaCore version, btw)

That I'm not so sure.  I do find them useful for archaeology.  My
current view mirrors Alexandre's here, so I'll just make his words
mine :-) :

 http://sourceware.org/ml/libc-alpha/2013-04/msg00100.html

> 
>> As someone that has done _lots_ of archaeology on gdb's code,
>> including going further back beyond the cvs import, I've often
>> had trouble matching ChangeLogs to mailing list discussions, and
>> then often will still not find a clear rationale if I actually
>> find a match.  I can only wish people had been doing it too
>> "back then".
> 
> Same on my end - I constantly go back in history, both with the FSF
> and AdaCore repositories, and found that they help tremendously.
> 


-- 
Pedro Alves

Re: contribution checklist in the wiki

[Joel Brobecker]

> That I'm not so sure.  I do find them useful for archaeology.  My
> current view mirrors Alexandre's here, so I'll just make his words
> mine :-) :
> 
>  http://sourceware.org/ml/libc-alpha/2013-04/msg00100.html

I don't want to open a debate over this, as we would first need
to switch to git in order for me to make a possibly-compelling
argument in favor of getting rid of them. But the reason why I got
rid of them at AdaCore is that git log has become a much more
powerful way to perform searches (you can limit the output using
criteria such as dates, or author, for instance). In the meantime,
they stopped getting in the way, as they were are a constant source
of merge/cherry-pick conflicts.

-- 
Joel

Re: contribution checklist in the wiki

[Pedro Alves]

On 05/22/2013 11:23 AM, Joel Brobecker wrote:

> I don't want to open a debate over this, 

Me neither.  :-)

> In the meantime,
> they stopped getting in the way, as they were are a constant source
> of merge/cherry-pick conflicts.

Funny, I have this URL open on my browser for weeks:

  http://thread.gmane.org/gmane.comp.lib.glibc.alpha/24003

But I haven't tried those yet.

-- 
Pedro Alves

Re: contribution checklist in the wiki

[Joel Brobecker]

> Funny, I have this URL open on my browser for weeks:
> 
>   http://thread.gmane.org/gmane.comp.lib.glibc.alpha/24003

Neat! I thought the script would have to be called post-merge
to fixup a merge issue, but looks like not. I will give it
a try.

Thanks :)

-- 
Joel

Re: contribution checklist in the wiki

[Eli Zaretskii]

> Date: Tue, 21 May 2013 18:55:17 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: GDB Patches <gdb-patches@sourceware.org>
> 
> As someone that has done _lots_ of archaeology on gdb's code,
> including going further back beyond the cvs import, I've often
> had trouble matching ChangeLogs to mailing list discussions, and
> then often will still not find a clear rationale if I actually
> find a match.  I can only wish people had been doing it too
> "back then".

Perhaps we should encourage contributors to point to URL of the
discussion thread.