============
Contributing
============

.. highlight:: bash

Contributions are welcome, :doc:`planned features <plans>` and
bug fixes in particular. But please `file a feature request
<https://github.com/odkr/para/issues/new>`_ before you start
implementing a feature, so that we can discuss it first.


Standards
=========

Please target C99_ and POSIX.1-2008_, and follow the `SEI CERT C Coding
Standard <CERT C_>`_. 


Style
=====

Please follow the `CERT C`_ recommendations, `OpenBSD style`_, and Robert 
Pike's `notes on programing in C <pikestyle_>`_, in that order. But indent
code with four spaces on every indentation level.


Tests
=====

Code should pass the test suite before being submitted.
Please :doc:`add tests <testing>` for your code, too.

Run the test suite::

    make check

Skip slow tests::

    make quickcheck

.. admonition:: System requirements

    Integration tests require a modern, POSIX.1-2008_-compliant shell.
    Recent-ish versions of the `GNU Bash`_, the Almquist shell and its
    decendents (incl. the BusyBox_ variant and the Debian Almquist
    shell), the `Korn Shell`_ and its decedents (incl. the MirOS and
    OpenBSD variants), `Yet Another Shell`_, and the `Z Shell`_ will do.

.. warning::
    Some tests examine Para's behavior under load and,
    to that end, *induce* system load, if only for less than a minute.

.. note::
    Some tests, when run with a development build, may report

    .. code::

        ==12345==WARNING: AddressSanitizer failed to allocate 0xfffffffffffffff8 bytes

    This is intentional. These tests provoke :c:macro:`ENOMEM`.


Code Analyzers
==============

Para ships with configurations for:

* Clang-Tidy_
* Cppcheck_
* Flawfinder_
* RATS_

Be so kind and test your code with Clang-Tidy *or* Cppcheck
and Flawfinder *or* RATS. 

Run all linters that are installed::

    make lint

Run Flawfinder and RATS only, if they are installed::

    make quicklint


Memory Checkers
===============

Para ships with test configurations for:

* Valgrind_
* leaks_

Please check your code for memory issues if a memory checker is at hand.

Check with Valgrind or :command:`leaks`, whichever is installed::

    make memcheck

.. tip::
    Use :option:`--read-var-info=yes` for more helpful diagnostics::

        make VALGRINDFLAGS=--read-var-info=yes memcheck


Automation
==========

Run

.. code:: bash
    
    git config core.hooksPath .githooks

to run :command:`make quickcheck quicklint` before each commit
and :command:`make check lint` before each push.


Version Control
===============

Para uses Git_ and follows the `Git Flow`_ branching model. The
source is hosted at `Codeberg <repo_>`_ (primary) and
`repo.or.cz <repo-mirror_>`_ (mirror).


Pull Requests
=============

`Fork Para <https://codeberg.org/odkr/para/fork>`_ on Codeberg.

Download the ``devel`` branch of your fork::

    git clone --branch devel "git@codeberg.org:${username:?}/para.git"

Set up Para as upstream source::

    git remote add upstream git@codeberg.org:odkr/para.git

Create a branch for your changes::

    git checkout -b feat-foo

Make your changes::

   vi para.c

Commit, rebase, and push::

    git add para.c
    git commit -S -m 'feat: Added support for foo'
    git pull --rebase upstream devel
    git push origin feat-foo

.. important::
    Please sign your commits.

Finally, submit your pull request. 


Patches
=======

You can also send a patch to the :file:`@zoho.com`
address listed in my `PGP key`_.

Download the ``devel`` branch::

    git clone --branch devel "git@codeberg.org:odkr/para.git"

Set up Para as upstream source::

    git remote add upstream git@codeberg.org:odkr/para.git

Create a branch for your changes::

    git checkout -b feat-foo

Make your changes::

    vi para.c

Commit and rebase::

    git add para.c
    git commit -S -m 'feat: Added support for foo'
    git pull --rebase upstream devel

Create a patch::

    git diff HEAD HEAD~1 >foo.patch

Please sign your patch::

    gpg -ab foo.patch