Contributing¶
Contributions are welcome, planned features and bug fixes in particular. But please file a feature request 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.
Style¶
Please follow the CERT C recommendations, OpenBSD style, and Robert Pike’s notes on programing in C, in that order. But indent code with four spaces on every indentation level.
Tests¶
Code should pass the test suite before being submitted. Please add tests for your code, too.
Run the test suite:
make check
Skip slow tests:
make quickcheck
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
==12345==WARNING: AddressSanitizer failed to allocate 0xfffffffffffffff8 bytes
This is intentional. These tests provoke ENOMEM.
Code Analyzers¶
Para ships with configurations for:
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:
Please check your code for memory issues if a memory checker is at hand.
Check with Valgrind or leaks, whichever is installed:
make memcheck
Tip
Use --read-var-info=yes for more helpful diagnostics:
make VALGRINDFLAGS=--read-var-info=yes memcheck
Automation¶
Run
git config core.hooksPath .githooks
to run make quickcheck quicklint before each commit and make check lint before each push.
Version Control¶
Para uses Git and follows the Git Flow branching model. The source is hosted at Codeberg (primary) and repo.or.cz (mirror).
Pull Requests¶
Fork Para 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 @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