[RFC/RFA] gdb/CONTRIBUTE update (most of the info is now on our wiki)

  A new contributor mentioned that some of the info in gdb/CONTRIBUTE
was either out of date, or in contradiction with recommendations
we now make, iso I decided to review the contents of this file. That's
when I noticed that a lot of it is now available in the Contribution
Checklist wiki page, which we maintain more actively (also, the wiki
version has web-related features not available to plain-text files).
So, this patch updates the gdb/CONTRIBUTE file to correct/remove
information in favor of links to the Contribution Checklist online.

gdb/ChangeLog:

        * CONTRIBUTE: Adjust the reference to the Internal Manual,
        now part of the GDB Wiki.  Add reference to the Contribution
        Checklist, also in the GDB Wiki.  Remove several parts of
        this file, which are redundent with the the contents provided
        by the Contribution Checklist.

Thoughts? OK to commit?

Thanks,
  

On 01/17/2016 08:24 AM, Joel Brobecker wrote:
>  gdb/CONTRIBUTE | 109 +++++++--------------------------------------------------
>  1 file changed, 13 insertions(+), 96 deletions(-)
> 
> diff --git a/gdb/CONTRIBUTE b/gdb/CONTRIBUTE
> index 30f51cc..ddb436c 100644
> --- a/gdb/CONTRIBUTE
> +++ b/gdb/CONTRIBUTE
> @@ -4,14 +4,20 @@
>  GDB is a collaborative project and one which wants to encourage new
>  development.  You may wish to fix GDB bugs, improve testing, port GDB
>  to a new platform, update documentation, add new GDB features, and the
> -like. To help with this, there is a lot of documentation
> -available.. In addition to the user guide and internals manual
> -included in the GDB distribution, the GDB web pages also contain much
> -information.
> +like. To help with this, there is a lot of documentation available.
> +In addition to the user guide included in the GDB distribution,
> +the GDB web pages also contain much information. The GDB Wiki, in
> +particular, is where we collect and document a lot of information
> +regarding the GDB development process:
>  
> -You may also want to submit your change so that can be considered for
> -conclusion in a future version of GDB (see below).  Regardless, we
> -encourage you to distribute the change yourself.
> +        https://sourceware.org/gdb/wiki/
> +
> +You may also want to submit your change so they can be considered for
> +inclusion in a future version of GDB (see below).  Regardless, we
> +encourage you to distribute the change yourself.  To help you create
> +high-quality contributions, we maintain a Contribution Checklist:
> +
> +        https://sourceware.org/gdb/wiki/ContributionChecklist
>  

Thanks a bunch for doing this.  It's been on my TODO for a long while
after this:

 https://sourceware.org/ml/gdb-patches/2014-10/msg00636.html

IMO, we'd keep this file even more minimal, and instead of having
it point to the wiki page here, it'd point to:

  https://sourceware.org/gdb/contribute/

(which is also linked from the main page)

and that page would be the one that would mention the wiki.

My main reason would that the the "contribute" page in the web site
would be the canonical entry point, while the wiki page is a fast
moving target.  E.g., it's growing past a checklist, so I wouldn't
be surprised if we end up splitting it into separate pages at some
point (and end up changing the URL).

But TBC, I'm definitely already happy with what you propose.

Thanks,
Pedro Alves
  

Hi Pedro,

> Thanks a bunch for doing this.  It's been on my TODO for a long while
> after this:
> 
>  https://sourceware.org/ml/gdb-patches/2014-10/msg00636.html
> 
> IMO, we'd keep this file even more minimal, and instead of having
> it point to the wiki page here, it'd point to:
> 
>   https://sourceware.org/gdb/contribute/
> 
> (which is also linked from the main page)
> 
> and that page would be the one that would mention the wiki.
> 
> My main reason would that the the "contribute" page in the web site
> would be the canonical entry point, while the wiki page is a fast
> moving target.  E.g., it's growing past a checklist, so I wouldn't
> be surprised if we end up splitting it into separate pages at some
> point (and end up changing the URL).
> 
> But TBC, I'm definitely already happy with what you propose.

Sorry for the late reply - busy week! I just wanted to say that
I tend to agree with your comments. I think we'll just need to
iron the details out.

One thing we might want to discuss: Editing the GDB web pages
(html repository) is not hard per se, but is inconvenient:
there are 2 CVS repositories to maintain in sync, with distinct
ACLs for pushing. I personally have the procedure down pat, but
I wouldn't recommend anyone else but one or two backups spend
anytime getting setup. So, instead, I am wondering: Why not
move the https://sourceware.org/gdb/contribute/ page to the Wiki?

This page could still be the entry point, and be the more stable
document; and then we could link to the checklist from there
as you are suggesting.

While discussion, I was trying to find ways to make the checklist
a little more like a checklist (something you go through quickly
and repetitively to make sure you haven't forgotten something
each time). Because of all the comments and annotations, it's
hard to go through it quickly, or not skip accidently a step.
I agree everyone is in great shape if only one or two are skipped
(;-)), but maybe there is a technical way we can only display
the subject of each item on the checklist, and then have a toggle
we can use to display/hide the explanations/rationale/examples...
Not something to discuss right away necessarily, but perhaps
something interesting.

I'll get back to this when I can; maybe not this weekend, but
the next one.
  

Hi Joel,

From the better-late-than-never department...

On 01/21/2016 10:14 AM, Joel Brobecker wrote:
> Hi Pedro,
> 
>> Thanks a bunch for doing this.  It's been on my TODO for a long while
>> after this:
>>
>>  https://sourceware.org/ml/gdb-patches/2014-10/msg00636.html
>>
>> IMO, we'd keep this file even more minimal, and instead of having
>> it point to the wiki page here, it'd point to:
>>
>>   https://sourceware.org/gdb/contribute/
>>
>> (which is also linked from the main page)
>>
>> and that page would be the one that would mention the wiki.
>>
>> My main reason would that the the "contribute" page in the web site
>> would be the canonical entry point, while the wiki page is a fast
>> moving target.  E.g., it's growing past a checklist, so I wouldn't
>> be surprised if we end up splitting it into separate pages at some
>> point (and end up changing the URL).
>>
>> But TBC, I'm definitely already happy with what you propose.
> 
> Sorry for the late reply - busy week! I just wanted to say that
> I tend to agree with your comments. I think we'll just need to
> iron the details out.
> 
> One thing we might want to discuss: Editing the GDB web pages
> (html repository) is not hard per se, but is inconvenient:
> there are 2 CVS repositories to maintain in sync, with distinct
> ACLs for pushing. I personally have the procedure down pat, but
> I wouldn't recommend anyone else but one or two backups spend
> anytime getting setup. So, instead, I am wondering: Why not
> move the https://sourceware.org/gdb/contribute/ page to the Wiki?

If only we'd move the website to git... :-)

> 
> This page could still be the entry point, and be the more stable
> document; and then we could link to the checklist from there
> as you are suggesting.

*nod*

> 
> While discussion, I was trying to find ways to make the checklist
> a little more like a checklist (something you go through quickly
> and repetitively to make sure you haven't forgotten something
> each time). Because of all the comments and annotations, it's
> hard to go through it quickly, or not skip accidently a step.
> I agree everyone is in great shape if only one or two are skipped
> (;-)), but maybe there is a technical way we can only display
> the subject of each item on the checklist, and then have a toggle
> we can use to display/hide the explanations/rationale/examples...
> Not something to discuss right away necessarily, but perhaps
> something interesting.
> 
> I'll get back to this when I can; maybe not this weekend, but
> the next one.
> 

At this point, I'm convinced that the file in the sources serves
no real use, and I'd just remove it entirely.  But, in any case,
I think the next best step would be to tweak
<https://sourceware.org/gdb/contribute/> to point at some gdb/wiki/contribute
page, as discussed above, instead of pointing at gdb/CONTRIBUTE in the sources.
That seems to be the main blocker.

Thanks,
Pedro Alves