So you want to hack on Bitmask? Thanks, and welcome!
This document assumes a
Tox is all you need:
Test when changes are made to common/soledad¶
If you are developing against a non-published branch of
leap.soledad, run instead:
tox -e py27-dev
soledad repos to be checked out in the
Setting up the development environment¶
There is an automated script that runs, sequentially, all the commands in the section below. In debian-based systems, you can get a fully working development environment with:
To activate the freshly created virtualenv the next time, you must use pew:
pew workon bitmask
the bootstrap script is, at the moment, quite opinionated. for instance, it installs and depends on pew, it checks out the bitmask-dev repo under ~/leap folder, and it assumes you are using zsh. if you think it should allow more freedom of choices, feel free to open a pull request.
Install the system-wide dependencies. For debian-based systems:
sudo apt install build-essential python-dev python-virtualenv \ libsqlcipher-dev libssl-dev libffi-dev \ python-pyqt5 python-pyqt5.qtwebkit
If you are going to be running tests that involve creating a lot of OpenPGP keys, and specially in vms, the following is also recommended to speed up things:
sudo apt install haveged
Clone the repo. The master branch has the latest code:
git clone https://0xacab.org/leap/bitmask-dev cd bitmask-dev
Create a virtualenv and activate it:
virtualenv venv source venv/bin/activate
By the way, if you plan to get into heavy development, you might want to consider using something like pew, instead of the plain virtualenv.
Now you should be able to install all the bitmask dependencies:
You can also install some dependencies that are going to be useful during development:
pip install -r pkg/requirements-dev.pip
Main Bitmask Components¶
The main bitmask-dev repo orchestrates the launching if the bitmaskd daemon. This is a collection of services that launches the vpn and mail services. bitmask vpn, mail and keymanager are the main modules, and soledad is one of the main dependencies for the mail service.
The Qt gui¶
The Qt gui is a minimalistic wrapper that uses PyQt5 to launch the core and
display a qt-webkit browser rendering the resources served by the core. Its main
entrypoint is in
to develop with the js ui, refer to
Bitmask privileged runner¶
For launching VPN and the firewall, Bitmask needs to run with administrative
privileges. In linux,
bitmask_root is the component that runs with root
privileges. We currently depend on
polkit to execute it as
root. In order to do that, Bitmask needs to put some policykit helper files in a
place that is root-writeable.
If you have installed Bitmask from some distro package, these folders should be already in place. If you’re running the Bitmask bundles, the first time you will be prompted to authenticate to allow these helpers to be copied over (or any time that these helpers change).
However, if you’re running bitmask in a headless environment, you will want to copy the helpers manually, without involving pkexec. To do that, use:
sudo `which bitmask_helpers` install
You can also uninstall them:
sudo `which bitmask_helpers` uninstall
How to contribute code¶
- Send your merge requests to https://0xacab/leap/bitmask-dev, it will be subject to code-review.
- Please base your branch for master, and keep it rebased when you push.
- After review, please squash your commits.
- Follow pep8 for all the python code.
- Git messages should be informative.
- There is a pre-commit hook ready to be used in the
docs/hooksfolder, alongside some other hooks to do autopep8 on each commit.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HOW TO USE THIS TEMPLATE: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Run `git config commit.template docs/hooks/leap-commit-template` or edit the .git/config for this project and add `template = docs/hooks/leap-commit-template` under the [commit] block ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ COMMIT TEMPLATE FORMAT EXPLAINED ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [type] <subject> <body> <footer> Type should be one of the following: - bug (bug fix) - feat (new feature) - docs (changes to documentation) - style (formatting, pep8 violations, etc; no code change) - refactor (refactoring production code) - test (adding missing tests, refactoring tests; no production code change) - pkg (packaging related changes; no production code change) - i18n translation related changes Subject should use imperative tone and say what you did. For example, use 'change', NOT 'changed' or 'changes'. The body should go into detail about changes made. The footer should contain any issue references or actions. You can use one or several of the following: - Resolves: #XYZ - Related: #XYZ - Documentation: #XYZ - Releases: XYZ The Documentation field should be included in every new feature commit, and it should link to an issue in the bug tracker where the new feature is analyzed and documented. For a full example of how to write a good commit message, check out https://github.com/sparkbox/how_to/tree/master/style/git
We try hard not to introduce any new dependencies at this moment. If you really have to, the packages bitmask depends on have to be specified both in the setup.py and the pip requirements file.
Don’t introduce any pinning in the setup.py file, they should go in the
requirements files (mainly
Signing your commits¶
For contributors with commit access, you should sign all your commits. If you are merging some code from external contributors, you should sign their commits.
For handy alias for sign and signoff commits from external contributors add to your gitconfig:
[alias] # Usage: git signoff-rebase [base-commit] signoff-rebase = "!GIT_SEQUENCE_EDITOR='sed -i -re s/^pick/e/' sh -c 'git rebase -i $1 && while test -f .git/rebase-merge/interactive; do git commit --amend --signoff --no-edit && git rebase --continue; done' -"
We avoid merge commits into master, they make a very messy history. Put this in your gitconfig to only allow the merges that can be resolved as a fast-forward:
[merge] ff = only
Making a new release¶
A checklist for the release process can be found here
As part of the release we also tag upload snapshots of the
cd ui make dist-build
and then you can upload it to pypi:
Want to help? Come talk to us on irc or the mailing list!
Some areas in which we always need contribution are:
- Localization of the client (talk to elijah).
- Multiplatform gitlab runners
- Windows and OSX packaging (talk to kali)
- Windows Firewall integration for VPN
- Migrating components to py3 (look for vshyba or kali).
- Minimal C++ Qt client (see kali’s bitmaskqt5 repo)