add CONTRIBUTING.md

9 files changed, 82 insertions, 37 deletions

diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
index 1cdba810..f90e13e1 100644
--- a/.github/ISSUE_TEMPLATE/bug.md
+++ b/.github/ISSUE_TEMPLATE/bug.md
@@ -5,11 +5,14 @@ title: "[OS] title"
 labels: 'bug'
 
 ---
-**Platform**
+## Platform
+
 * { OS version }
 * { psutil version (print psutil.__version__) }
 * { python version }
 
 
-**Bug description**
+## Bug description
+
 ...
+
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 00000000..39dc113f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a question
+    url: https://groups.google.com/g/psutil
+    about: Use this to ask for support
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000..88f416f0
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,9 @@
+## Resume
+
+* OS: { OS name }
+* Bug fix: { yes/no }
+* Fixes: { comma-separated list of tickets fixed by the PR, if any }
+
+## Description
+
+...
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..69c9dd94
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,33 @@
+Contributing to psutil project
+==============================
+
+Issues
+------
+
+* The issue tracker is for reporting problems or proposing enhancements related
+  to the **program code**.
+* Please do not open issues **asking for support**. Instead, use the forum at:
+  https://groups.google.com/g/psutil.
+* Before submitting a new issue, **search** if there are existing issues for
+  the same topic.
+* **Be clear** in describing what the problem is and try to be accurate in
+  editing the default issue **template**. There is a bot which automatically
+  assigns **labels** based on issue's title and body format. Labels help
+  keeping the issues properly organized and searchable (by OS, issue type, etc.).
+* To report a **security vulnerability**, use the
+  [Tidelift security contact](https://tidelift.com/security).
+  Tidelift will coordinate the fix and the disclosure of the reported problem.
+
+Pull Requests
+-------------
+
+* The PR system is for fixing bugs or make enhancements related to the
+  **program code**.
+* If you whish to implement a new feature or add support for a new platform it's
+  better to **discuss it first**, either on the issue tracker, the forum or via
+  private email.
+* In order to get acquainted with the code base and tooling, take a look at the
+  **[Development Guide](https://github.com/giampaolo/psutil/blob/master/docs/DEVGUIDE.rst)**.
+* If you can, remember to update
+  [HISTORY.rst](https://github.com/giampaolo/psutil/blob/master/HISTORY.rst)
+  and [CREDITS](https://github.com/giampaolo/psutil/blob/master/CREDITS) file.
diff --git a/HISTORY.rst b/HISTORY.rst
index 58626e10..99e85a5b 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -12,7 +12,8 @@ XXXX-XX-XX
 - 1872_: [Windows] added support for PyPy 2.7.
 - 1879_: provide pre-compiled wheels for Linux and macOS (yey!).
 - 1880_: get rid of Travis and Cirrus CI services (they are no longer free).
-  CI testing is now done by GitHub Actions on Linux, macOS and FreeBSD (yes). AppVeyor is still being used for Windows CI.
+  CI testing is now done by GitHub Actions on Linux, macOS and FreeBSD (yes).
+  AppVeyor is still being used for Windows CI.
 
 **Bug fixes**
 
diff --git a/MANIFEST.in b/MANIFEST.in
index 2bed87e7..d651cd4e 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,6 +1,7 @@
 include .coveragerc
 include .flake8
 include .gitignore
+include CONTRIBUTING.md
 include CREDITS
 include HISTORY.rst
 include INSTALL.rst
diff --git a/README.rst b/README.rst
index ec323253..837446a9 100644
--- a/README.rst
+++ b/README.rst
@@ -74,7 +74,7 @@
         <a href="https://github.com/giampaolo/psutil/blob/master/INSTALL.rst"><b>Install</b></a>&nbsp;&nbsp;&nbsp;
         <a href="https://psutil.readthedocs.io/"><b>Documentation</b></a>&nbsp;&nbsp;&nbsp;
         <a href="https://pypi.org/project/psutil/#files"><b>Download</b></a>&nbsp;&nbsp;&nbsp;
-        <a href="http://groups.google.com/group/psutil/topics"><b>Forum</b></a>&nbsp;&nbsp;&nbsp;
+        <a href="https://groups.google.com/g/psutil"><b>Forum</b></a>&nbsp;&nbsp;&nbsp;
         <a href="https://gmpy.dev/tags/psutil"><b>Blog</b></a>&nbsp;&nbsp;&nbsp;
         <a href="#funding"><b>Funding</b></a>&nbsp;&nbsp;&nbsp;
         <a href="https://github.com/giampaolo/psutil/blob/master/HISTORY.rst"><b>What's new</b></a>&nbsp;&nbsp;&nbsp;
@@ -135,6 +135,11 @@ None yet.
 
     <sup><a href="https://github.com/sponsors/giampaolo">add your avatar</a></sup>
 
+Contributing
+============
+
+See `CONTRIBUTING.md<https://github.com/giampaolo/psutil/blob/master/HISTORY.rst>`__ guidelines.
+
 Example usages
 ==============
 
diff --git a/docs/DEVGUIDE.rst b/docs/DEVGUIDE.rst
index 2ed8c42a..cb9545bc 100644
--- a/docs/DEVGUIDE.rst
+++ b/docs/DEVGUIDE.rst
@@ -1,13 +1,13 @@
-Setup
-=====
+psutil development guide
+========================
+
+Build, setup and running tests
+..............................
 
 psutil makes extensive use of C extension modules, meaning a C compiler is
 required, see
 `install instructions <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__.
 
-Build, setup and running tests
-===============================
-
 Once you have a compiler installed:
 
 .. code-block:: bash
@@ -51,7 +51,7 @@ Once you have a compiler installed:
     make test -p C:\python35\python.exe  # Windows
 
 Coding style
-============
+------------
 
 - python code strictly follows `PEP-8`_ styling guides and this is enforced by
   a commit GIT hook installed via ``make install-git-hooks`` which will reject
@@ -59,7 +59,7 @@ Coding style
 - C code should follow `PEP-7`_ styling guides.
 
 Code organization
-=================
+-----------------
 
 .. code-block:: bash
 
@@ -70,7 +70,7 @@ Code organization
     psutil/tests/test_{platform}.py      # platform-specific test suite
 
 Adding a new API
-================
+----------------
 
 Typically, this is what you do:
 
@@ -86,62 +86,49 @@ Typically, this is what you do:
   This usually means testing the return value of the new API against
   a system CLI tool.
 - update the doc in ``doc/index.py``.
-- update ``HISTORY.rst``.
+- update `HISTORY.rst`_ and `CREDITS`_ files.
 - make a pull request.
 
 Make a pull request
-===================
+-------------------
 
 - fork psutil (go to https://github.com/giampaolo/psutil and click on "fork")
-- git clone the fork locally: ``git clone git@github.com:YOUR-USERNAME/psutil.git``)
+- git clone the fork locally: ``git clone git@github.com:YOUR-USERNAME/psutil.git``
 - create a branch:``git checkout -b new-feature``
 - commit your changes: ``git commit -am 'add some feature'``
 - push the branch: ``git push origin new-feature``
-- create a new PR by via GitHub web interface
+- create a new PR via the GitHub web interface and sign-off your work (see
+  `CONTRIBUTING.md`_ guidelines)
 
 Continuous integration
-======================
-
-All of the services listed below are automatically run on each ``git push``.
-
-Unit tests
-----------
+----------------------
 
-Tests are automatically run on every GIT push and PR on **Linux**, **macOS**,
+Unit tests are automatically run on every ``git push`` on **Linux**, **macOS**,
 **Windows** and **FreeBSD** by using:
 
 - `Github Actions`_ (Linux, macOS, Windows)
 - `Appveyor`_ (Windows)
 
-.. image:: https://img.shields.io/github/workflow/status/giampaolo/psutil/CI?label=linux%2C%20macos%2C%20freebsd
+.. image:: https://img.shields.io/github/workflow/status/giampaolo/psutil/CI?label=Linux%2C%20macOS%2C%20FreeBSD
     :target: https://github.com/giampaolo/psutil/actions?query=workflow%3ACI
 
-.. image:: https://img.shields.io/appveyor/ci/giampaolo/psutil/master.svg?maxAge=3600&label=windows
+.. image:: https://img.shields.io/appveyor/ci/giampaolo/psutil/master.svg?maxAge=3600&label=Windows
     :target: https://ci.appveyor.com/project/giampaolo/psutil
 
 OpenBSD, NetBSD, AIX and Solaris does not have continuos test integration.
 
-Test coverage
--------------
-
-Test coverage is provided by `coveralls.io`_.
-
-.. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
-    :target: https://coveralls.io/github/giampaolo/psutil?branch=master
-    :alt: Test coverage (coverall.io)
-
 Documentation
-=============
+-------------
 
 - doc source code is written in a single file: `/docs/index.rst`_.
 - doc can be built with ``make setup-dev-env; cd docs; make html``.
 - public doc is hosted at https://psutil.readthedocs.io
 
-
 .. _`appveyor.yml`: https://github.com/giampaolo/psutil/blob/master/appveyor.yml
 .. _`Appveyor`: https://ci.appveyor.com/project/giampaolo/psuti
 .. _`coveralls.io`: https://coveralls.io/github/giampaolo/psuti
 .. _`CREDITS`: https://github.com/giampaolo/psutil/blob/master/CREDITS
+.. _`CONTRIBUTING.md`: https://github.com/giampaolo/psutil/blob/master/CONTRIBUTING.md
 .. _`doc/index.rst`: https://github.com/giampaolo/psutil/blob/master/doc/index.rst
 .. _`Github Actions`: https://github.com/giampaolo/psutil/actions
 .. _`HISTORY.rst`: https://github.com/giampaolo/psutil/blob/master/HISTORY.rst
diff --git a/docs/index.rst b/docs/index.rst
index a99ab206..ee5863c3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,9 +10,10 @@ Quick links
 
 - `Home page <https://github.com/giampaolo/psutil>`__
 - `Install <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_
-- `Blog <https://gmpy.dev/tags/psutil>`__
 - `Forum <http://groups.google.com/group/psutil/topics>`__
 - `Download <https://pypi.org/project/psutil/#files>`__
+- `Blog <https://gmpy.dev/tags/psutil>`__
+- `Contributing <https://github.com/giampaolo/psutil/blob/master/CONTRIBUTING.md>`__
 - `Development guide <https://github.com/giampaolo/psutil/blob/master/docs/DEVGUIDE.rst>`_
 - `What's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst>`__