How to participate¶
If you found some bug in the codebase or documentation, or you want some improvement in ‘Polemarch’ project, you can easily inform us about it. Here is how to proceed:
Create (or find if it already exists) an issue for problem you want to solve. Maybe somebody is already working on it or maybe during discussion becomes clear that it is not a problem at all.
To investigate problem, you probably must be able to run cloned project. To do so install required dependencies. See “Install from PyPI” for more detailed explanation, which dependencies and why they are needed. System packages (example for Ubuntu 16.04):
sudo apt-get install python-pip python-dev libffi-dev libssl-dev git sshpass libyaml-dev
Note: Your patch must work at Python 2 and Python 3. For Python 3 you should have at least Python 3.4.5, because older Python 3 may not work correctly with Polemarch.
Make sure you have latest pip and virtualenv in your system. You can do it with those commands:
sudo pip install --upgrade pip sudo pip install --upgrade virtualenv
Create virtualenv for Polemarch. It is only supported method to run Polemarch. Don’t try to install it system-wide or locally using
pip install --user.
mkdir polemarch_project cd polemarch_project virtualenv venv source venv/bin/activate
Make fork of our repository and clone it to your local development machine.
git clone https://gitlab.com/vstconsulting/polemarch.git
Create a branch for your work named with number of issue:
cd polemarch git checkout -b issue_1
Install python dependencies:
pip install -r requirements-git.txt -r requirements.txt -r requirements-doc.txt tox
Initialize empty database with all required stuff (tables and so on) for Polemarch:
Enable debug in settings.ini. You can edit
polemarch/main/settings.inibut make sure that changes in that file does not goes to you commit. Or you can copy
/etc/polemarch/settings.ini(default settings location for Polemarch). Type
debug = truein section
[main]. Otherwise there will be no available static files and debug features when you start development web-server.
Run Polemarch GUI with web-server and investigate with your debugger how it works to find out what need to be changed:
# run web-server python polemarchctl webserver
This command also starts worker, if you have added worker options in
/etc/polemarch/settings.ini. More about worker section you can find on “Install from PyPI”.
If you want to see console output of Polemarch webserver during it work, you need to add following option in
[uwsgi] daemon = false
You may also want to change
log_levelfor easy debugging.
Write tests for your changes (we prefer TDD approach). Execute those tests with all other Polemarch’s tests by:
make test ENVS=flake,pylint
This command do PEP8 check of codebase and static analyzing with pylint and flake. Make sure that your code meets those checks.
Reflect your changes in documentation (if needed). Build documentation, read what you have changed and make sure that all is right. To build documentation use:
Make commit. We prefer commit messages with briefly explanations of your changes. Unacceptable: “issue #1” or “fix”. Acceptable: “fix end slashes for GET in docs”.
Create pull request and refer it in issue.
ATTENTION: You must agree to our contributor agreement to prevent any license problems to project in future with your contribution.
That’s it. Thank you for your contribution.