update devguide

1 files changed, 61 insertions, 128 deletions

diff --git a/docs/DEVGUIDE.rst b/docs/DEVGUIDE.rst
index 6f4b00e8..dec86f51 100644
--- a/docs/DEVGUIDE.rst
+++ b/docs/DEVGUIDE.rst
@@ -1,140 +1,91 @@
 Setup
 =====
 
-psutil makes extensive use of C extensions, so you'll need a C compiler and
-Python headers.
-
-Linux
------
-
-Ubuntu / Debian::
-
-    sudo apt-get install gcc python3-dev
-
-RedHat / CentOS::
-
-    sudo yum install gcc python3-devel
-
-macOS
------
-
-Install `Xcode <https://developer.apple.com/downloads/?name=Xcode>`__.
-
-Windows
--------
-
-On Windows you'll need **Visual Studio** (Mingw32 is not supported).
-This `blog post <https://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/>`__
-provides numerous info on how to properly set up VS. The needed VS versions are:
-
-* Python 2.6, 2.7: `VS-2008 <http://www.microsoft.com/en-us/download/details.aspx?id=44266>`__
-* Python 3.4: `VS-2010 <http://www.visualstudio.com/downloads/download-visual-studio-vs#d-2010-express>`__
-* Python 3.5+: `VS-2015 <http://www.visualstudio.com/en-au/news/vs2015-preview-vs>`__
-
-Compiling 64 bit versions of Python 2.6 and 2.7 with VS 2008 requires
-`Windows SDK and .NET Framework 3.5 SP1 <https://www.microsoft.com/en-us/download/details.aspx?id=3138>`__.
-Once installed run `vcvars64.bat`
-(see `here <http://stackoverflow.com/questions/11072521/>`__).
-
-Other platforms
----------------
-
-See `install <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__
-instructions.
+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
 
-  git clone git@github.com:giampaolo/psutil.git
-  make setup-dev-env
-  make install
-  make test
+    git clone git@github.com:giampaolo/psutil.git
+    make setup-dev-env  # install useful dev libs (flake8, coverage, ...)
+    make build
+    make install
+    make test
 
-- bear in mind that ``make``(see `Makefile`_) is the designated tool to run
-  tests, build, install etc. and that it is also available on Windows (see
+- ``make``(see `Makefile`_) is the designated tool to run tests, build, install
+  try new features you're developing, etc. This also includes Windows (see
   `make.bat`_ ).
-- do not use ``sudo``; ``make install`` installs psutil as a limited user in
-  "edit" mode; also ``make setup-dev-env`` installs deps as a limited user.
-- use `make help` to see the list of available commands.
-
-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``.
-- C code follows `PEP-7`_ styling guides.
-
-Makefile
-========
-
-Some useful make commands:
+  Some useful commands are:
 
 .. code-block:: bash
 
-    make install
-    make setup-dev-env   # install useful dev libs (flake8, unittest2, etc.)
-    make test            # run unit tests
     make test-parallel   # faster
     make test-memleaks
     make test-coverage
     make lint            # Python (PEP8) and C linters
+    make uninstall
+    make help
 
-There are some differences between ``make`` on UNIX and Windows.
-For instance, to run a specific Python version. On UNIX:
+- if you're working on a new feature and you whish to compile & test it "on the
+  fly" from a test script, this is a quick & dirty way to do it:
 
 .. code-block:: bash
 
-    make test PYTHON=python3.5
-
-On Windows:
+    make test TSCRIPT=test_script.py  # on UNIX
+    make test test_script.py          # on Windows
 
-.. code-block:: bat
+- do not use ``sudo``. ``make install`` installs psutil as a limited user in
+  "edit" mode, meaning you can edit psutil code on the fly while you develop.
 
-    make -p C:\python35\python.exe test
-
-If you want to modify psutil and run a script on the fly which uses it do
-(on UNIX):
+- if you want to target a specific Python version:
 
 .. code-block:: bash
 
-    make test TSCRIPT=foo.py
-
-On Windows:
-
-.. code-block:: bat
+    make test PYTHON=python3.5           # UNIX
+    make test -p C:\python35\python.exe  # Windows
 
-    make test foo.py
+Coding style
+============
 
-Adding a new feature
-====================
+- 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
+  commits if code is not PEP-8 complieant.
+- C code should follow `PEP-7`_ styling guides.
 
-Usually the files involved when adding a new functionality are:
+Code organization
+=================
 
 .. code-block:: bash
 
-    psutil/__init__.py                   # main psutil namespace
-    psutil/_ps{platform}.py              # python platform wrapper
-    psutil/_psutil_{platform}.c          # C platform extension
-    psutil/_psutil_{platform}.h          # C header file
+    psutil/__init__.py                   # main psutil namespace ("import psutil")
+    psutil/_ps{platform}.py              # platform-specific python wrapper
+    psutil/_psutil_{platform}.c          # platform-specific C extension
     psutil/tests/test_process|system.py  # main test suite
-    psutil/tests/test_{platform}.py      # platform specific test suite
+    psutil/tests/test_{platform}.py      # platform-specific test suite
+
+Adding a new API
+================
 
-Typical process occurring when adding a new functionality (API):
+Typically, this is what you do:
 
-- define the new function in `psutil/__init__.py`_.
+- define the new API in `psutil/__init__.py`_.
 - write the platform specific implementation in ``psutil/_ps{platform}.py``
   (e.g. `psutil/_pslinux.py`_).
-- if the change requires C, write the C implementation in
+- if the change requires C code, write the C implementation in
   ``psutil/_psutil_{platform}.c`` (e.g. `psutil/_psutil_linux.c`_).
 - write a generic test in `psutil/tests/test_system.py`_ or
   `psutil/tests/test_process.py`_.
-- if possible, write a platform specific test in
+- if possible, write a platform-specific test in
   ``psutil/tests/test_{platform}.py`` (e.g. `psutil/tests/test_linux.py`_).
-  This usually means testing the return value of the new feature against
+  This usually means testing the return value of the new API against
   a system CLI tool.
-- update doc in ``doc/index.py``.
+- update the doc in ``doc/index.py``.
 - update ``HISTORY.rst``.
 - make a pull request.
 
@@ -142,52 +93,44 @@ Make a pull request
 ===================
 
 - fork psutil (go to https://github.com/giampaolo/psutil and click on "fork")
-- git clone your fork locally: ``git clone git@github.com:YOUR-USERNAME/psutil.git``)
-- create your feature branch:``git checkout -b new-feature``
+- 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 to the branch: ``git push origin new-feature``
-- create a new pull request by via github web interface
-- remember to update `HISTORY.rst`_ and `CREDITS`_ files.
+- push the branch: ``git push origin new-feature``
+- create a new PR by via GitHub web interface
 
 Continuous integration
 ======================
 
-All of the services listed below are automatically run on ``git push``.
+All of the services listed below are automatically run on each ``git push``.
 
 Unit tests
 ----------
 
-Tests are automatically run for every GIT push on **Linux**, **macOS** and
-**Windows** by using:
+Tests are automatically run on every GIT push on **Linux**, **macOS**,
+**Windows** and **FreeBSD** by using:
 
 - `Travis`_ (Linux, macOS)
+- `Github Actions`_ (Linux, macOS, Windows)
 - `Appveyor`_ (Windows)
-
-Test files controlling these are `.travis.yml`_ and `appveyor.yml`_.
-Both services run psutil test suite against all supported python version
-(2.6 - 3.6).
-Two icons in the home page (README) always show the build status:
+- `Cirrus CI`_ (FreeBSD)
 
 .. image:: https://img.shields.io/travis/giampaolo/psutil/master.svg?maxAge=3600&label=Linux,%20OSX,%20PyPy
     :target: https://travis-ci.org/giampaolo/psutil
-    :alt: Linux, macOS and PyPy3 tests (Travis)
 
 .. image:: https://img.shields.io/appveyor/ci/giampaolo/psutil/master.svg?maxAge=3600&label=Windows
     :target: https://ci.appveyor.com/project/giampaolo/psutil
-    :alt: Windows tests (Appveyor)
 
 .. image:: https://img.shields.io/cirrus/github/giampaolo/psutil?label=FreeBSD
     :target: https://cirrus-ci.com/github/giampaolo/psutil-cirrus-ci
-    :alt: FreeBSD tests (Cirrus-CI)
 
-BSD, AIX and Solaris are currently tested manually.
+OpenBSD, NetBSD, AIX and Solaris does not have continuos test integration.
 
 Test coverage
 -------------
 
 Test coverage is provided by `coveralls.io`_ and it is controlled via
 `.travis.yml`_.
-An icon in the home page (README) always shows the last coverage percentage:
 
 .. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
     :target: https://coveralls.io/github/giampaolo/psutil?branch=master
@@ -197,26 +140,18 @@ Documentation
 =============
 
 - doc source code is written in a single file: `/docs/index.rst`_.
-- it uses `RsT syntax`_
-  and it's built with `sphinx`_.
 - doc can be built with ``make setup-dev-env; cd docs; make html``.
-- public doc is hosted on http://psutil.readthedocs.io/
-
-Releasing a new version
-=======================
-
-These are notes for myself (Giampaolo):
+- public doc is hosted at https://psutil.readthedocs.io
 
-- ``make release``
-- post announce (``make print-announce``) on psutil and python-announce mailing
-  lists, twitter, g+, blog.
 
-
-.. _`.travis.yml`: https://github.com/giampaolo/psutil/blob/master/.travis.ym
-.. _`appveyor.yml`: https://github.com/giampaolo/psutil/blob/master/appveyor.ym
+.. _`.travis.yml`: https://github.com/giampaolo/psutil/blob/master/.travis.yml
+.. _`appveyor.yml`: https://github.com/giampaolo/psutil/blob/master/appveyor.yml
 .. _`Appveyor`: https://ci.appveyor.com/project/giampaolo/psuti
+.. _`Cirrus CI`: https://cirrus-ci.com/github/giampaolo/psutil-cirrus-ci
 .. _`coveralls.io`: https://coveralls.io/github/giampaolo/psuti
+.. _`CREDITS`: https://github.com/giampaolo/psutil/blob/master/CREDITS
 .. _`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
 .. _`make.bat`: https://github.com/giampaolo/psutil/blob/master/make.bat
 .. _`Makefile`: https://github.com/giampaolo/psutil/blob/master/Makefile
@@ -231,5 +166,3 @@ These are notes for myself (Giampaolo):
 .. _`RsT syntax`: http://docutils.sourceforge.net/docs/user/rst/quickref.htm
 .. _`sphinx`: http://sphinx-doc.org
 .. _`Travis`: https://travis-ci.org/giampaolo/psuti
-.. _`HISTORY.rst`: https://github.com/giampaolo/psutil/blob/master/HISTORY.rst
-.. _`CREDITS`: https://github.com/giampaolo/psutil/blob/master/CREDITS