Replace contribution list in CONTRIBUTE file with wiki link
Commit Message
The GDB wiki page has a much better contribution checklist than
that in the GDB CONTRIBUTE file. In addition, the wiki is easier
to keep up to date with current processes.
Reduce the CONTRIBUTE file down to two short paragraphs with links
to both the contribution process and the GDB homepage. This also
ensures anyone reading the CONTRIBUTE file for a given release has
access to the latest processes.
gdb/ChangeLog:
2019-01-23 Alan Hayward <alan.hayward@arm.com>
* CONTRIBUTE: Replace contribution list with wiki link.
---
gdb/CONTRIBUTE | 147 +++++--------------------------------------------
1 file changed, 14 insertions(+), 133 deletions(-)
Comments
On 2019-01-23 4:46 a.m., Alan Hayward wrote:
> The GDB wiki page has a much better contribution checklist than
> that in the GDB CONTRIBUTE file. In addition, the wiki is easier
> to keep up to date with current processes.
>
> Reduce the CONTRIBUTE file down to two short paragraphs with links
> to both the contribution process and the GDB homepage. This also
> ensures anyone reading the CONTRIBUTE file for a given release has
> access to the latest processes.
>
> gdb/ChangeLog:
>
> 2019-01-23 Alan Hayward <alan.hayward@arm.com>
>
> * CONTRIBUTE: Replace contribution list with wiki link.
> ---
> gdb/CONTRIBUTE | 147 +++++--------------------------------------------
> 1 file changed, 14 insertions(+), 133 deletions(-)
>
> diff --git a/gdb/CONTRIBUTE b/gdb/CONTRIBUTE
> index 30f51ccdc7..e9a96e59bf 100644
> --- a/gdb/CONTRIBUTE
> +++ b/gdb/CONTRIBUTE
> @@ -4,142 +4,23 @@
> 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 and internals manual included in the GDB
> +distribution, the GDB web pages also contain much information.
>
> 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.
> +conclusion in a future version of GDB. For a full guide on how to
> +submit patches see:
Is it just me, or the "You may also..." sentence is very weird? conclusion
or inclusion? There seems to be a missing work after "so that".
Otherwise, this LGTM, thanks.
Simon
On 01/23/2019 09:46 AM, Alan Hayward wrote:
> +https://sourceware.org/gdb/wiki/ContributionChecklist
I'd rather point at https://sourceware.org/gdb/contribute/
and then have _that_ point at some page in the wiki.
That's what I had suggested in the other thread.
The reason is that the <https://sourceware.org/gdb/contribute/>
URL is going to be more stable than a wiki link, which we can
rename, split, etc. a bit more freely. The contribution checklist page
is quite large by now, and I've heard of people wishing for a smaller more
concise entry point. The checklist was meant to be that, a checklist.
A "how to contribute" page may have some higher level info to
get people started.
Thanks,
Pedro Alves
Combing both threads. New version below
> On 23 Jan 2019, at 16:03, Pedro Alves <palves@redhat.com> wrote:
>
> On 01/23/2019 09:46 AM, Alan Hayward wrote:
>
>> +https://sourceware.org/gdb/wiki/ContributionChecklist
>
> I'd rather point at https://sourceware.org/gdb/contribute/
> and then have _that_ point at some page in the wiki.
> That's what I had suggested in the other thread.
> The reason is that the <https://sourceware.org/gdb/contribute/>
> URL is going to be more stable than a wiki link, which we can
> rename, split, etc. a bit more freely. The contribution checklist page
> is quite large by now, and I've heard of people wishing for a smaller more
> concise entry point. The checklist was meant to be that, a checklist.
> A "how to contribute" page may have some higher level info to
> get people started.
>
> Thanks,
> Pedro Alves
Fair enough. Having the double link seemed redundant, but your
reasoning makes sense.
The sourceware contribute page itself needs an update (it currently
points to the CONTRIBUTE file!) How do we go about making that change?
> On 23 Jan 2019, at 15:21, Simon Marchi <simon.marchi@ericsson.com> wrote:
>
> On 2019-01-23 4:46 a.m., Alan Hayward wrote:
>>
>> 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.
>> +conclusion in a future version of GDB. For a full guide on how to
>> +submit patches see:
>
> Is it just me, or the "You may also..." sentence is very weird? conclusion
> or inclusion? There seems to be a missing work after "so that".
>
> Otherwise, this LGTM, thanks.
>
> Simon
Agreed. I missed that.
Wanted to avoid rewriting as much as possible. But now I’m wondering if it
maybe needs reducing down a little more.
How about the following (can repost with proper diff, but easier to read
if I just paste it)
Contributing to GDB
GDB is a collaborative project that relies on contributions. You can
help in this! You may wish to fix bugs, improve testing, port GDB to
a new platform, update documentation, add new features or optimizations,
contribute to the mailing lists or offical GDB website, etc. We welcome
all of the above and feel free to ask on the GDB mailing lists if you are
looking for feedback or for people to review a work in progress. For
more information see:
https://sourceware.org/gdb/
In order for any code patches to be considered for submission, please
also see the contribution guide:
https://sourceware.org/gdb/contribute/
On 01/23/2019 05:15 PM, Alan Hayward wrote:
> Combing both threads. New version below
>
>> On 23 Jan 2019, at 16:03, Pedro Alves <palves@redhat.com> wrote:
>>
>> On 01/23/2019 09:46 AM, Alan Hayward wrote:
>>
>>> +https://sourceware.org/gdb/wiki/ContributionChecklist
>>
>> I'd rather point at https://sourceware.org/gdb/contribute/
>> and then have _that_ point at some page in the wiki.
>> That's what I had suggested in the other thread.
>> The reason is that the <https://sourceware.org/gdb/contribute/>
>> URL is going to be more stable than a wiki link, which we can
>> rename, split, etc. a bit more freely. The contribution checklist page
>> is quite large by now, and I've heard of people wishing for a smaller more
>> concise entry point. The checklist was meant to be that, a checklist.
>> A "how to contribute" page may have some higher level info to
>> get people started.
> Fair enough. Having the double link seemed redundant, but your
> reasoning makes sense.
>
> The sourceware contribute page itself needs an update (it currently
> points to the CONTRIBUTE file!) How do we go about making that change?
>
That has been the (mental) blocker for me thus far. The webpages are
still in CVS somewhere. I never touched it myself.
Joel, can you guide us here?
AFAIK the current process is that commits go to both sourceware.org's CVS and
to another copy in gnu.org as well for the https://www.gnu.org/software/gdb/ .
I had chatted with Joel at the Cauldron about streamlining this, and the
conclusion seemed to be that there's no real blocker for making the gnu.org
version simply a redirect to sourceware.org. That would simplify things. The
other neat step would be to migrate to git. :-)
> Wanted to avoid rewriting as much as possible. But now I’m wondering if it
> maybe needs reducing down a little more.
>
> How about the following (can repost with proper diff, but easier to read
> if I just paste it)
Yeah.
It'd to be good to make sure to migrate any useful info being
deleted, if not covered in the web site already, rather than just
losing it, IMHO, though. I think most of the steps in the file
are covered by the checklist wiki, but the larger/expanded intro
text currently in gdb/CONTRIBUTE would be useful on
the https://sourceware.org/gdb/contribute/ landing page, I believe.
>
>
>
> Contributing to GDB
>
> GDB is a collaborative project that relies on contributions. You can
> help in this! You may wish to fix bugs, improve testing, port GDB to
> a new platform, update documentation, add new features or optimizations,
> contribute to the mailing lists or offical GDB website, etc. We welcome
typo in "offical".
> all of the above and feel free to ask on the GDB mailing lists if you are
> looking for feedback or for people to review a work in progress. For
> more information see:
>
> https://sourceware.org/gdb/
>
>
> In order for any code patches to be considered for submission, please
> also see the contribution guide:
I'm not very keen on this sentence since there's more to contribution that
code patches: bug triaging, testing, helping users on the gdb mailing
list, etc.
>
> https://sourceware.org/gdb/contribute/
>
>
Since this whole file is all about contributing, I think we can replace
both URLs with a single URL pointing at the contribution page, and
drop the "in order for any ..." sentence altogether. I.e., just say:
~~~
... looking for feedback or for people to review a work in progress. For
more information see:
https://sourceware.org/gdb/contribute/
~~~
Once there, it should be trivial and obvious for a user to reach the homepage.
Thanks,
Pedro Alves
> That has been the (mental) blocker for me thus far. The webpages are
> still in CVS somewhere. I never touched it myself.
> Joel, can you guide us here?
There are two CVS repositories as you mentioned. One is on sourceware
(sourceware.org:/cvs/gdb/htdocs), and one is on Savannah. For now,
it is easier for me if you just send me the patch you want to commit,
and I do it. Otherwise, the re-synchronization on my end can be painful.
> AFAIK the current process is that commits go to both sourceware.org's CVS and
> to another copy in gnu.org as well for the https://www.gnu.org/software/gdb/ .
> I had chatted with Joel at the Cauldron about streamlining this, and the
> conclusion seemed to be that there's no real blocker for making the gnu.org
> version simply a redirect to sourceware.org. That would simplify things. The
> other neat step would be to migrate to git. :-)
Do you guys know who to ask to get the redirection?
And before we do, should we perhaps consider the opposite redirection?
In other words, redirect from sourceware.org to gnu.org/software/gdb?
One strong requirement before we can consider it is that Savannah first
support git repositories. It seems to be possible:
https://savannah.gnu.org/maintenance/UsingGit/
The secondary problem would then become - figuring out how to
automate the auto-update of the website upon pushing new changes.
The redirect to sourceware might make things easier, but it would
be a one-off action item, and then things would be on the GNU server.
Just not the best time for me to take on another task, unfortunately
:-(.
In the meantime, I'm happy to push changes sent to me. That part
just takes a couple of minutes each time.
> On 24 Jan 2019, at 13:00, Pedro Alves <palves@redhat.com> wrote:
>
> On 01/23/2019 05:15 PM, Alan Hayward wrote:
>> Combing both threads. New version below
>>
>>> On 23 Jan 2019, at 16:03, Pedro Alves <palves@redhat.com> wrote:
>>>
>>> On 01/23/2019 09:46 AM, Alan Hayward wrote:
>>>
>>>> +https://sourceware.org/gdb/wiki/ContributionChecklist
>>>
>>> I'd rather point at https://sourceware.org/gdb/contribute/
>>> and then have _that_ point at some page in the wiki.
>>> That's what I had suggested in the other thread.
>>> The reason is that the <https://sourceware.org/gdb/contribute/>
>>> URL is going to be more stable than a wiki link, which we can
>>> rename, split, etc. a bit more freely. The contribution checklist page
>>> is quite large by now, and I've heard of people wishing for a smaller more
>>> concise entry point. The checklist was meant to be that, a checklist.
>>> A "how to contribute" page may have some higher level info to
>>> get people started.
>
>> Fair enough. Having the double link seemed redundant, but your
>> reasoning makes sense.
>>
>> The sourceware contribute page itself needs an update (it currently
>> points to the CONTRIBUTE file!) How do we go about making that change?
>>
>
> That has been the (mental) blocker for me thus far. The webpages are
> still in CVS somewhere. I never touched it myself.
> Joel, can you guide us here?
>
> AFAIK the current process is that commits go to both sourceware.org's CVS and
> to another copy in gnu.org as well for the https://www.gnu.org/software/gdb/ .
> I had chatted with Joel at the Cauldron about streamlining this, and the
> conclusion seemed to be that there's no real blocker for making the gnu.org
> version simply a redirect to sourceware.org. That would simplify things. The
> other neat step would be to migrate to git. :-)
>
>
>> Wanted to avoid rewriting as much as possible. But now I’m wondering if it
>> maybe needs reducing down a little more.
>>
>> How about the following (can repost with proper diff, but easier to read
>> if I just paste it)
>
> Yeah.
>
> It'd to be good to make sure to migrate any useful info being
> deleted, if not covered in the web site already, rather than just
> losing it, IMHO, though. I think most of the steps in the file
> are covered by the checklist wiki, but the larger/expanded intro
> text currently in gdb/CONTRIBUTE would be useful on
> the https://sourceware.org/gdb/contribute/ landing page, I believe.
>
>>
>>
>>
>> Contributing to GDB
>>
>> GDB is a collaborative project that relies on contributions. You can
>> help in this! You may wish to fix bugs, improve testing, port GDB to
>> a new platform, update documentation, add new features or optimizations,
>> contribute to the mailing lists or offical GDB website, etc. We welcome
>
> typo in "offical".
>
>> all of the above and feel free to ask on the GDB mailing lists if you are
>
>> looking for feedback or for people to review a work in progress. For
>> more information see:
>>
>> https://sourceware.org/gdb/
>>
>>
>> In order for any code patches to be considered for submission, please
>> also see the contribution guide:
>
> I'm not very keen on this sentence since there's more to contribution that
> code patches: bug triaging, testing, helping users on the gdb mailing
> list, etc.
>
>>
>> https://sourceware.org/gdb/contribute/
>>
>>
>
> Since this whole file is all about contributing, I think we can replace
> both URLs with a single URL pointing at the contribution page, and
> drop the "in order for any ..." sentence altogether. I.e., just say:
>
> ~~~
> ... looking for feedback or for people to review a work in progress. For
> more information see:
>
> https://sourceware.org/gdb/contribute/
> ~~~
>
> Once there, it should be trivial and obvious for a user to reach the homepage.
>
> Thanks,
> Pedro Alves
With those changes, we now have:
Contributing to GDB
GDB is a collaborative project that relies on contributions. You can
help in this! You may wish to fix bugs, improve testing, port GDB to
a new platform, update documentation, add new features or optimizations,
contribute to the mailing lists or official GDB website, etc. We welcome
all of the above and feel free to ask on the GDB mailing lists if you are
looking for feedback or for people to review a work in progress. For
more information see:
https://sourceware.org/gdb/contribute/
For the webpage, how about the following. Everything in a [] is a link which
needs replacing with the relevant link from the list at the end (and the list
itself deleted).
Contributing to GDB
GDB is a collaborative project that relies on contributions. You can help in this! You may wish to fix bugs, improve testing, port GDB to a new platform, update documentation, add new features or optimizations, contribute to the mailing lists or official GDB website, etc. We welcome all of the above and feel free to ask on the [GDB Mailing Lists] if you are looking for feedback or for people to review a work in progress.
To help with this, there is plenty of documentation available. In addition to the [User Guide] and [Internals Manual] included in the GDB distribution, the [GDB Wiki] also contain substantial information. If you are looking for a project then check the [Project Ideas] page.
If you write a change to the GDB codebase we encourage you to distribute the change yourself. You may also want to submit your change so that can be considered for inclusion in a future version of GDB. If so then there are certain legal requirements and style issues which all contributors need to be aware of - for more details please read the [Contribution Checklist].
[GDB Mailing Lists] https://sourceware.org/gdb/mailing-lists/
[User Guide] https://sourceware.org/gdb/current/onlinedocs/gdb/
[Internals Manual] https://sourceware.org/gdb/wiki/Internals
[GDB Wiki] https://sourceware.org/gdb/wiki/
[Project Ideas] https://sourceware.org/gdb/wiki/ProjectIdeas
[Contribution Checklist] https://sourceware.org/gdb/wiki/ContributionChecklist
Alan.
On 01/25/2019 02:30 PM, Alan Hayward wrote:
> With those changes, we now have:
>
> Contributing to GDB
>
> GDB is a collaborative project that relies on contributions. You can
> help in this!
Doesn't "help in" sound odd? I'd expect "help with" to be more
correct here?
> You may wish to fix bugs, improve testing, port GDB to
> a new platform, update documentation, add new features or optimizations,
> contribute to the mailing lists or official GDB website, etc. We welcome
> all of the above and feel free to ask on the GDB mailing lists if you are
> looking for feedback or for people to review a work in progress. For
> more information see:
>
> https://sourceware.org/gdb/contribute/
I'd put a blank line before "For more information see:", like:
~~~
GDB is a collaborative project that relies on contributions. You can
help with this! You may wish to fix bugs, improve testing, port GDB
to a new platform, update documentation, add new features or
optimizations, contribute to the mailing lists or official GDB
website, etc. We welcome all of the above and feel free to ask on the
GDB mailing lists if you are looking for feedback or for people to
review a work in progress.
For more information see:
https://sourceware.org/gdb/contribute/
~~~
>
>
>
>
> For the webpage, how about the following. Everything in a [] is a link which
> needs replacing with the relevant link from the list at the end (and the list
> itself deleted).
>
>
>
> Contributing to GDB
>
> GDB is a collaborative project that relies on contributions. You can help in this! You may wish to fix bugs, improve testing, port GDB to a new platform, update documentation, add new features or optimizations, contribute to the mailing lists or official GDB website, etc. We welcome all of the above and feel free to ask on the [GDB Mailing Lists] if you are looking for feedback or for people to review a work in progress.
>
> To help with this, there is plenty of documentation available. In addition to the [User Guide] and [Internals Manual] included in the GDB distribution, the [GDB Wiki] also contain substantial information. If you are looking for a project then check the [Project Ideas] page.
"also contain" -> "also contains"
>
> If you write a change to the GDB codebase we encourage you to distribute the change yourself. You may also want to submit your change so that can be considered for inclusion in a future version of GDB. If so then there are certain legal requirements and style issues which all contributors need to be aware of - for more details please read the [Contribution Checklist].
>
>
> [GDB Mailing Lists] https://sourceware.org/gdb/mailing-lists/
> [User Guide] https://sourceware.org/gdb/current/onlinedocs/gdb/
> [Internals Manual] https://sourceware.org/gdb/wiki/Internals
> [GDB Wiki] https://sourceware.org/gdb/wiki/
> [Project Ideas] https://sourceware.org/gdb/wiki/ProjectIdeas
> [Contribution Checklist] https://sourceware.org/gdb/wiki/ContributionChecklist
>
>
Looks good to me!
Thanks,
Pedro Alves
FWIW, the proposed text with Pedro's comments looks good to me.
Let me know when you have a final version you'd like me to push,
and I will take care of it.
@@ -4,142 +4,23 @@
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 and internals manual included in the GDB
+distribution, the GDB web pages also contain much information.
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.
+conclusion in a future version of GDB. For a full guide on how to
+submit patches see:
-If you don't feel up to hacking GDB, there are still plenty of ways to
-help! You can answer questions on the mailing lists, write
-documentation, find bugs, create a GDB related website (contribute to
-the official GDB web site), or create a GDB related software
-package. We welcome all of the above and feel free to ask on the GDB
-mailing lists if you are looking for feedback or for people to review
-a work in progress.
-
-Ref: http://www.gnu.org/software/gdb/
-
-Finally, there are certain legal requirements and style issues which
-all contributors need to be aware of.
-
-o Coding Standards
-
- All contributions must conform to the GNU Coding Standard.
- Submissions which do not conform to the standards will be
- returned with a request to reformat the changes.
-
- Ref: http://www.gnu.org/prep/standards_toc.html
-
- GDB has certain additional coding requirements. Those
- requirements are explained in the GDB internals documentation.
-
- Ref: http://sourceware.org/gdb/wiki/Internals%20Coding-Standards
-
-
-o Copyright Assignment
-
- Before we can accept code contributions from you, we need a
- copyright assignment form filled out and filed with the FSF.
-
- See some documentation by the FSF for details and contact us
- (either via the GDB mailing list or the GDB maintainer that is
- taking care of your contributions) to obtain the relevant
- forms.
-
- Small changes can be accepted without a copyright assignment form
- on file.
-
- Ref: http://www.gnu.org/prep/maintain.html#SEC6
-
-
-o Submitting Patches
-
- Every patch must have several pieces of information before we
- can properly evaluate it.
-
- A description of the bug and how your patch fixes this
- bug. A reference to a testsuite failure is very helpful. For
- new features a description of the feature and your
- implementation.
-
- A ChangeLog entry as plaintext (separate from the patch); see
- the various ChangeLog files for format and content. Note that,
- unlike some other projects, we do require ChangeLogs also for
- documentation (i.e., .texi files).
-
- The patch itself. If you are accessing the git repository, use
- "git diff", remembering first to update to the current master;
- else, use "diff -up OLD NEW". If your version of diff does not
- support these options, then get the latest version of GNU diff.
-
- We accept patches as plain text (preferred for the compilers
- themselves), MIME attachments (preferred for the web pages),
- or as uuencoded gzipped text.
+https://sourceware.org/gdb/wiki/ContributionChecklist
- When you have all these pieces, bundle them up in a mail
- message and send it to gdb-patches@sourceware.org. All
- patches and related discussion should be sent to the
- gdb-patches mailinglist. For further information on the GDB
- git repository, see the Anonymous read-only git access and
- Read-write git access page.
---
-
-Supplemental information for GDB:
-
-o Please try to run the relevant testsuite before and after
- committing a patch
-
- If the contributor doesn't do it then the maintainer will. A
- contributor might include before/after test results in their
- contribution.
-
-
-o For bug fixes, please try to include a way of
- demonstrating that the patch actually fixes something.
-
- The best way of doing this is to ensure that the
- testsuite contains one or more test cases that
- fail without the fix but pass with the fix.
-
- People are encouraged to submit patches that extend
- the testsuite.
-
-
-o Please read your patch before submitting it.
-
- A patch containing several unrelated changes or
- arbitrary reformats will be returned with a request
- to re-formatting / split it.
-
-
-o If ``gdb/configure.ac'' is modified then you don't
- need to include patches to the regenerated file
- ``configure''.
-
- The maintainer will re-generate those files
- using autoconf (2.64 as of 2009-08-22).
-
-
-o If ``gdb/gdbarch.sh'' is modified, you don't
- need to include patches to the generated files
- ``gdbarch.h'' and ``gdbarch.c''.
-
- See ``gdb/configure.ac'' above.
-
-
-o When submitting a patch that fixes a bug
- in GDB's bug database a brief reference
- to the bug can be included in the ChangeLog
- vis
-
- * CONTRIBUTE: Mention PR convention.
- Fix PR gdb/4705.
+If you don't feel up to hacking GDB, there are still plenty of ways to
+help! You can answer questions on the mailing lists, write
+documentation, find bugs, create a GDB related website, contribute to
+the official GDB web site, or create a GDB related software package.
+We welcome all of the above and feel free to ask on the GDB mailing
+lists if you are looking for feedback or for people to review a work
+in progress. For more information see:
- The text ``PR gdb/4705'' should also be included
- in the git commit message. That causes the
- patch to automatically be archived with the PR.
+https://sourceware.org/gdb/