[docs] add hacking section to the readme

I've tried to clarify a little the (confuse) relationships with other
pieces and repos.

- Resolves: #39

1 files changed, 26 insertions, 3 deletions

diff --git a/README.rst b/README.rst
index d792dcf..64119e3 100644
--- a/README.rst
+++ b/README.rst
@@ -3,10 +3,14 @@ RiseupVPN
 
 Anonymous VPN. Easy, fast, secure.
 
-This repo has everything needed to build BitmaskLite/RiseupVPN on different platforms
-(windows, mac and linux).
+This repo has everything needed to build BitmaskLite/RiseupVPN on different
+platforms (windows, mac and linux).
 
-RiseupVPN is a branded build of Bitmask Lite. Bitmask Lite is a minimal rewrite of the Bitmask VPN Client, written in golang, that for now lacks client authentication, and is preconfigured to use a single provider. As of this moment, it is built for a single provider (riseup.net), but it should be easy to customize for other providers.
+RiseupVPN is a branded build of Bitmask Lite. Bitmask Lite is a minimal rewrite
+of the Bitmask VPN Client, written in golang, that for now lacks client
+authentication, and is preconfigured to use a single provider. As of this
+moment, it is built for a single provider (riseup.net), but it should be easy
+to customize for other providers.
 
 
 Install
@@ -107,3 +111,22 @@ You can also cross-compile openvpn::
   git clone https://github.com/OpenVPN/openvpn-build
   cd openvpn-build/windows-nsis
   CHOST=x86_64-w64-mingw32 CBUILD=i686-pc-cygwin ./build
+
+Hacking
+---------------
+
+If you want to contribute to BitmaskLite/RiseupVPN, you can get in contact with us in the ``#leap`` channel at freenode.
+
+You might also want to have a look at some related pieces that are used to build these packages.
+
+* `bitmask-systray`_: this is the golang implementation of RiseupVPN. It is
+  basically a wrapper around openvpn, with knowledge of what configuration
+  files are expected to exist in a LEAP provider. The only user interface is a minimalistic systray that uses libappindicator.
+* `the bitmask helper`_: it lives in this repo. It implements a long-lived helper that runs with administrative privileges, used in OSX and Windows for launching openvpn and the firewall. In OSX it is run as a LaunchDaemon, and in Windows we use nssm to run this helper. It communicates with BitmaskLite via a local http service.
+* `bitmask-root`_: for the snaps, in GNU/Linux we use a one-shot privileged helper that relies on policykit to elevate privileges without asking for password each time, instead of the long-lived helper that we use in osx and windows packages (although there is a linux implementation, and this long-lived helper might make sense in some cases, we want to explore that. For instance for OpenWRT packages).
+
+  In case you are wondering what is the relationship of BitmaskLite and the regular Bitmask, it is planned that the bitmask client will at some point switch to use the same helpers. This repo probably will be turned into a generic packaging and helper tool to be used for both branded builds of BitmaskLite, and packaging of the frozen python payloads generated from bitmask-dev.
+
+.. _`bitmask-systray`: https://0xacab.org/leap/bitmask-systray
+.. _`the bitmask helper`: https://0xacab.org/leap/riseup_vpn/tree/master/helper
+.. _`bitmask-root`: https://0xacab.org/leap/bitmask-dev/blob/master/src/leap/bitmask/vpn/helpers/linux/bitmask-root