Contributions#
Contributions are welcome, bug fixes and SASL mechanisms in particular. If you want to contribute another feature, consider filing a feature request first, so that we can discuss things beforehand.
STANDARDS#
Please target Python version 3.9 and follow PEP 8, PEP 20, PEP 257 as well as the spirit of Robert Pike’s Notes on Programing in C. Code should pass linting and the test suite. But you are welcome to ask for help if you are stuck.
LINTERS#
SieveManager ships with configurations for:
It would be kind of you if you made sure that your code passes every linter before your submit it. However, feel free to skip as many of them as you like if you do not want to install that many applications. Bandit and MyPy are the important ones.
Install the above linters:
pip3 -r linters.txt
Run MyPy, Bandit, and vermin only:
make quicklint
Run all linters:
make lint
Set the sources macro to override which files are linted, for example:
make lint sources=sievemgr.py
TESTING#
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
Set the checks macro to override which tests are run, for example:
make checks=tests.test_acap check
AUTOMATION#
Run
git config core.hooksPath .githooks
to automatically run make quicklint and make quickcheck before each commit and make lint and make check before each push.
Note
.githooks only ships with the Git respository.
It is not included in the tarball.
VERSION CONTROL#
SieveManager uses Git and follows the Git Flow branching model. The source code is hosted at Codeberg (primary) and NotABug (secondary).
PULL REQUESTS#
Fork SieveManager on Codeberg or NotABug.
Download the devel branch of your fork:
git clone --branch devel "git@${host:?}:${username:?}/sievemgr.git"
Set up SieveManger as upstream source:
git remote add upstream git@codeberg.org:odkr/sievemgr.git
Create a branch for your changes:
git checkout -b feat-foo
Make your changes:
vi sievemgr.py
Commit, rebase, and push:
git add sievemgr.py
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/sievemgr.git"
Set up SieveManger as upstream source:
git remote add upstream git@codeberg.org:odkr/sievemgr.git
Create a branch for your changes:
git checkout -b feat-foo
Make your changes:
vi sievemgr.py
Commit and rebase:
git add sievemgr.py
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