Developing and Contributing¶
Contributions to py3status including documentation, the core code, or for new or existing modules are welcome.
What you will need¶
- python3/python2
- pytest pytest-flake8
Setting up a developement environment¶
First clone the git repository
# using https
git clone https://github.com/ultrabug/py3status.git
# using ssh (needs github account)
git clone git@github.com:ultrabug/py3status.git
Run setup.py to install
# cd to the directory containing setup.py
cd py3status
# install you may need to use sudo to have required permissions
python setup.py develop
you can now run py3status and any changes to the code you make will active.
Note
py3status will only be installed for the version of python that you used
to run setup.py
. To run against a different version of python
You should repeat the above step eg python2.7 setup.py develop
.
If you wish to have multiple versions available. First run setup.py
develop
using the required python versions. Next copy the
executable eg sudo cp /usr/bin/py3status /usr/bin/py3status2
Then
edit the hashbang to point to your chosen python version.
Python versions¶
py3status code, including modules, should run under both python 2 and python 3.
Pytest¶
Py3status uses pytest and the pytest-flake8 plugin for testing. All submissions to the project must pass testing. To install these via pip use
pip install pytest
pip install pytest-flake8
The tests can be run by using py.test --flake8
in the py3status root directory.
Tests are kept in the tests
directory.
Travis CI¶
When you create your Pull Request, some checks from Travis CI will automatically run; you can see previous builds if you want to.
If something fails in the CI:
- Take a look the build log
- If you don’t get what is failing or why it is failing, feel free to tell it as a comment in your PR: people here are helpful and open-minded :)
- Once the problem is identified and fixed, rebase your commit with the fix and push it on your fork to trigger the CI again
For reference, you can take a look at this PR; you won’t see the old failed CI runs, but you’ll get an idea of the PR flow.
Coding in containers¶
Warning, by default (at least on
Archlinux),
i3status has cap_net_admin capabilities, which will make it fail with
operation not permitted
when running inside a Docker container.
$ getcap `which i3status`
/usr/sbin/i3status = cap_net_admin+ep
To allow it to run without these capabilites (hence disabling some of the functionnalities), remove it with:
setcap -r `which i3status`
Building documentation¶
Py3status documentation is build using sphinx
. The requirements
needed to build the documentation are in doc/doc-requirements.txt
make sure you have them installed.
To build the documentation.
# cd to the doc directory
cd doc
# build documentation
make html
The created documentation will be found in _build/html
Contributions¶
To make a contribution please create a pull request.