Contributing¶
Contributions are welcome, but consider filing a feature request before you start implementing a feature, so that we can discuss things beforehand.
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¶
Running 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
Warning
Some tests examine Para’s behavior under load and, to that end, induce system load, if only for less than a minute.
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 MirBSD, NetBSD, and OpenBSD variants), Yash, and the Z Shell will do. Unit tests require a system that is compatbiel with 4.4BSD (most Unix-like systems are, including Linux-based ones).
Known issues¶
Some tests fail on some systems when run with a development build
and address space layout randomization is enabled. Disable ASan by
passing -fno-sanitize=address to ./configure
to make those tests pass.
Some unit tests, when run with a development build, report:
==1234==WARNING: AddressSanitizer failed to allocate 0xfffffffffffffff8 bytes
This is intentional. These tests provoke ENOMEM.
Some tests ignore Ctrl-C.
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 and mirrored at repo.or.cz.
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