Setup and running tests
=======================

If you plan on hacking on psutil this is what you're supposed to do first:

- clone the GIT repository:

.. code-block:: bash

  $ git clone git@github.com:giampaolo/psutil.git

- install test deps and GIT hooks:

.. code-block:: bash

  make setup-dev-env

- run tests:

.. code-block:: bash

  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.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:

.. code-block:: bash

    make install        # install
    make setup-dev-env  # install useful dev libs (flake8, unittest2, etc.)
    make test           # run unit tests
    make test-memleaks  # run memory leak tests
    make test-coverage  # run test coverage
    make flake8         # run PEP8 linter

There are some differences between ``make`` on UNIX and Windows.
For instance, to run a specific Python version. On UNIX:

.. code-block:: bash

    make test PYTHON=python3.5

On Windows:

.. code-block:: bat

    set PYTHON=C:\python35\python.exe && make test

...or:

.. code-block:: bat

    make -p 35 test

If you want to modify psutil and run a script on the fly which uses it do
(on UNIX):

.. code-block:: bash

    make test TSCRIPT=foo.py

On Windows:

.. code-block:: bat

    make test foo.py

Adding a new feature
====================

Usually the files involved when adding a new functionality are:

.. 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/tests/test_process|system.py  # main test suite
    psutil/tests/test_{platform}.py      # platform specific test suite

Typical process occurring when adding a new functionality (API):

- define the new function 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
  ``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
  ``psutil/tests/test_{platform}.py`` (e.g. `psutil/tests/test_linux.py`_).
  This usually means testing the return value of the new feature against
  a system CLI tool.
- update doc in ``doc/index.py``.
- update ``HISTORY.rst``.
- make a pull request.

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``
- 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

Continuous integration
======================

All of the services listed below are automatically run on ``git push``.

Unit tests
----------

Tests are automatically run for every GIT push on **Linux**, **macOS** and
**Windows** by using:

- `Travis`_ (Linux, macOS)
- `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:

.. image:: https://img.shields.io/travis/giampaolo/psutil/master.svg?maxAge=3600&label=Linux%20/%20macOS
    :target: https://travis-ci.org/giampaolo/psutil
    :alt: Linux and macOS 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)

BSD, AIX and Solaris are currently tested manually.

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
    :alt: Test coverage (coverall.io)

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):

- ``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
.. _`Appveyor`: https://ci.appveyor.com/project/giampaolo/psuti
.. _`coveralls.io`: https://coveralls.io/github/giampaolo/psuti
.. _`doc/index.rst`: https://github.com/giampaolo/psutil/blob/master/doc/index.rst
.. _`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
.. _`PEP-7`: https://www.python.org/dev/peps/pep-0007/
.. _`PEP-8`: https://www.python.org/dev/peps/pep-0008/
.. _`psutil/__init__.py`: https://github.com/giampaolo/psutil/blob/master/psutil/__init__.py
.. _`psutil/_pslinux.py`: https://github.com/giampaolo/psutil/blob/master/psutil/_pslinux.py
.. _`psutil/_psutil_linux.c`: https://github.com/giampaolo/psutil/blob/master/psutil/_psutil_linux.c
.. _`psutil/tests/test_linux.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_linux.py
.. _`psutil/tests/test_process.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_process.py
.. _`psutil/tests/test_system.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_system.py
.. _`RsT syntax`: http://docutils.sourceforge.net/docs/user/rst/quickref.htm
.. _`sphinx`: http://sphinx-doc.org
.. _`Travis`: https://travis-ci.org/giampaolo/psuti
