[pgpool-hackers: 3428] Re: [PATCH] Add CONTRIBUTING file

[Alejandro Roman]

On Fri, Sep 13, 2019 at 09:07:18AM +0900, Tatsuo Ishii wrote:
> Hi Alejandro,
> 
> > As propossed in [1] several weeks ago, I have made an initial draft for a
> > CONTRIBUTING file.  I think this would make it easier for new contributors to
> > get started with the project.  I tried to refer to existing documentation
> > instead of writing it again (e.g. redirect to the wiki pages).  Any observation
> > is appreciated.
> > 
> > [1] https://www.pgpool.net/pipermail/pgpool-hackers/2019-August/003393.html
> 
> Thank you for your patch. This looks pretty good and I agree that
> including the document as a file in the source tree is a good
> idea. However, I also think that converting this to an SGML file so
> that it appears as a section in the docs as well. This may introduce
> small maintenance headache as there are two identical contents but
> it's more convenient for (potential) developers. What do you think?

I agree with you about the maintance headache if we keep two identical
contents.  I think this CONTRIBUTING file could go into the `Preface`
section of the docs, between the "Further information" and "Restrictions"
headers, perhaps under the title of "Contributing".

Also, I noticed that some information given in the CONTRIBUTING file is
already present in the docs, specifically the "Bugs" and "Our channels"
sections of the file.  For this reason, I think these two sections could be
removed from the "Contributing" page.

On the other hand, if the contents of the CONTRIBUTING file get moved to
the docs, I still think that a CONTRIBUTING file should be kept in the
source tree.  This is because it is a convention in open source projects
to have that file and it will probably be looked for by new
contributors.  This CONTRIBUTING file could only have a message and a
link to the "Contributing" page at the docs.

By the way, considering the problem with double contents, I found the TODO
file in the source tree and the TODO from wiki page confussing when I was
figuring out how to contribute to the project.  Considering also that the
TODO file hasn't been updated since 2011 (at least in the master
branch), what would you say if we delete it's content and put a
reference to the TODO wiki page instead?

Best regards,

Alejandro