[pgpool-hackers: 3424] [PATCH] Add CONTRIBUTING file

Alejandro Roman alejandro at aromnn.com
Fri Sep 13 08:34:31 JST 2019


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
-------------- next part --------------
>From 46a3f78a8c23725c7c29fda2ff0e3eccce917a10 Mon Sep 17 00:00:00 2001
From: Alejandro Roman <alejandro at aromnn.com>
Date: Thu, 12 Sep 2019 18:07:18 -0500
Subject: [PATCH] Add CONTRIBUTING file

A CONTRIBUTING file in the source code might make it easier for new
contributors to get into the project.  The file added by this commit
should be considered an initial draft.  I tried to put references to
existing sources (e.g. the wiki pages) and not to repeat what has
already been written.
---

See previous discussion at
https://www.pgpool.net/pipermail/pgpool-hackers/2019-August/003392.html

 CONTRIBUTING | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 CONTRIBUTING

diff --git a/CONTRIBUTING b/CONTRIBUTING
new file mode 100644
index 00000000..ecd0a4bc
--- /dev/null
+++ b/CONTRIBUTING
@@ -0,0 +1,107 @@
+CONTRIBUTING
+============
+
+Thank you for taking your time for contributing to Pgpool-II.  In this document,
+you will find references about where to fill bug cases and where to get in touch
+with the Pgpool-II community.  Also, you will find information about how to send
+your contributions to the project.
+
+
+Bugs
+----
+
+If you find a bug, you can report it in our bug tracking tool at [1].  You can
+also find more information about the tool and how to use it in the wiki at [2].
+
+
+Our channels
+------------
+
+As with the PostgreSQL community, we mainly base our communication through
+mailing lists.  You can find our mailing lists and their descriptions in our
+wiki at [3].
+
+
+Where to start
+--------------
+
+For first-time contributions, you can start by correcting or updating the docs
+at [4].  Also, we keep an updated list of TODO items at [5].  We send updates
+to the TODO list through the pgpool-hackers mailing lists, so be sure to check
+it regularly!
+
+
+Making your contribution
+---------------------------
+
+Unless you are planning to make trivial changes, we recommend you to send a
+message to 'pgpool-hackers at pgpool.net' first asking for comments about your
+contribution before implementing it.  This way, you can get notified in case
+another user has been implementing the same contribution.  In addition, you
+can also receive sugestions from more experienced contributors.  For this kind
+of requests, prefix your email subject with '[RFC]' or 'Request for comments'.
+An example of this flow can be found at [6] and it's thread at [7].
+
+The general workflow for making a contribution is:
+
+# 1. Clone the git project (see [8])
+git clone git://git.postgresql.org/git/pgpool2.git
+cd pgpool2
+
+# 2. Create a new topic branch
+git checkout -b my-topic-branch
+
+# 3. Code
+...
+
+# 4. Commit
+git add .
+git commit -v
+
+If your changes affect several modules, avoid committing them all together.
+Instead, divide them into logical groups and commit them one by one with
+`git add -p`.
+
+Keep your commit message to 80 or less characters, using present tense instead
+of past tense.  Think that each commit should tell what it is applying to the
+project, not what you did some time ago.  Also, capitalize the commit message
+and don't end it with a period.  Some examples of bad commit messages are:
+
+# Wrong, it should use present tense
+'Added a validation for X component'
+
+# Wrong, it shouldn't end with a period
+'Fix a typo in intro.sgml.'
+
+# Wrong, it should be capitalized
+'tweat build parameters'
+
+# Good
+'Fix indentation in c-library.mp4'
+
+For the commit body, don't just explain the what, but the why of the changes.
+This will help actual and future contributors understand your decisions.
+
+Finally, send your contribution as a patch to the pgpool-hackers mailing list.
+
+# 7. Get the patch
+git format-patch --patience master
+# Or with diff
+git diff --patience master my-topic-branch > my-cool-feature.patch
+
+For more recomendations on how to send patches, you can see the PostgreSQL
+guidelines at [9] and [10].
+
+A word of caution: some mail providers (like Gmail) wrap your email lines,
+which may corrupt your commit.  In this case, send the patch as an attachment.
+
+[1] https://www.pgpool.net/mantisbt/my_view_page.php
+[2] http://pgpool.net/mediawiki/index.php/Bug_tracking_system
+[3] http://pgpool.net/mediawiki/index.php/Mailing_lists
+[4] https://www.pgpool.net/mediawiki/index.php/Documentation
+[5] https://www.pgpool.net/mediawiki/index.php/TODO
+[6] http://www.sraoss.jp/pipermail/pgpool-hackers/2017-March/002213.html
+[7] http://www.sraoss.jp/pipermail/pgpool-hackers/2017-April/002271.html
+[8] https://pgpool.net/mediawiki/index.php/Source_code_repository]
+[9] https://wiki.postgresql.org/wiki/Submitting_a_Patch
+[10] https://wiki.postgresql.org/wiki/Working_with_git
-- 
2.20.1 (Apple Git-117)



More information about the pgpool-hackers mailing list