Contributing¶
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. Substantial contributions should follow the SOLID design pattern. Code should pass linting and the test suite.
Linters¶
SieveManager ships with configurations for:
It would be kind if you made sure that your code passes Bandit or Dlint to check for security issues, MyPy or Pyright to check for type errors, Ruff or Pylint to check the coding style, and vermin to check whether your code runs in Python 3.9.
Install all of the above, save for Pyright:
pip3 -r linters.txt
Run MyPy and Bandit only:
make quicklint
Run all linters:
make lint
Set the srcs macro to override which files are linted, for example:
make srcs=sievemgr.py lint
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 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 SieveManager 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 SieveManager 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