[docs] split development docs

the page was becoming too cluttered.

1 files changed, 35 insertions, 195 deletions

diff --git a/docs/hacking/index.rst b/docs/hacking/index.rst
index f3bad11d..007e87f9 100644
--- a/docs/hacking/index.rst
+++ b/docs/hacking/index.rst
@@ -1,21 +1,20 @@
-:LastChangedDate: $LastChangedDate$
+:LastChangedDate: $LastChangedDate$ 
 :LastChangedRevision: $LastChangedRevision$
 :LastChangedBy: $LastChangedBy$
 
 Hacking
 ========================================
 
-So you want to hack on Bitmask?
-Thanks, and welcome!
+So you want to hack on Bitmask?  Thanks, and welcome!
 
 This document assumes a ``Linux`` environment.
 
-There are also ongoing documents with notes for setting up an :ref:`osx <osx-dev>` and a
-:ref:`windows <win-dev>` working environments too, contribution is very much
-welcome on those docs!
+There are also ongoing documents with notes for setting up an :ref:`OSX
+<osx-dev>` and a :ref:`Windows <win-dev>` working environments too,
+contribution is very much welcome on those docs!
 
 Running tests
----------------------------------
+-------------
 
 Tox is all you need::
 
@@ -33,214 +32,55 @@ If you are developing against a non-published branch of ``leap.common`` or
 This expects ``leap_common`` and ``soledad`` repos to be checked out in the
 parent folder.
 
-.. _devenv:
 
-Setting up the development environment
---------------------------------------
+Architecture
+------------ 
 
-Automated procedure
-~~~~~~~~~~~~~~~~~~~
+There is a small :ref:`explanation of the bitmask components <architecture>`
+that might be helpful to get you started
+with the different moving parts of the Bitmask codebase.
 
-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::
+User Interface
+--------------
 
-  make dev-bootstrap
+The :ref:`Javascript User Interface <uidev>` has its own guide for developers.
 
-To activate the freshly created virtualenv the next time, you must use `pew`_::
+Setup
+-----
 
-  pew workon bitmask
+Read how to :ref:`setup your python development environment <devenv>` to start coding in no time.
 
-.. note:: 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.
-
-Manual instructions 
-~~~~~~~~~~~~~~~~~~~
-
-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::
-
-  make dev-latest-all
-
-You can also install some dependencies that are going to be useful during
-development::
-
-  pip install -r pkg/requirements-dev.pip
-
-
-.. _`pew`: https://pypi.python.org/pypi/pew
-
-
-Main Bitmask Components
----------------------------------
-
-The Core
-~~~~~~~~
-
-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 ``gui/app.py``.
-
-The Javascript UI
-~~~~~~~~~~~~~~~~~
-
-A modern javascript app is the main Bitmask Frontend. For instructions on how
-to develop with the js ui, refer to ``ui/README.md``.
-
-The Thunderbird Extension
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The development for the Thunderbird Extension happens on `this repo`_.
-This extension gets published to the `mozilla addons page`_.
-
-.. _`this repo`: https://0xacab.org/leap/bitmask_thunderbird
-.. _`mozilla addons page`: https://addons.mozilla.org/en-US/thunderbird/addon/bitmask
-
-
-Debugging Bitmask
----------------------------------
+Debug
+-----
 
 A must-read for debugging the Bitmask Core daemon is the :ref:`manhole HowTo <manhole>`.
 
+Privileges
+----------
 
-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 ``pkexec`` and ``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 
-
-
-.. note: split a Contributing page on its own, this is getting too long/messy
-
-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.
- 
-
-Coding conventions
----------------------------------
-
-* 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/hooks`` folder,
-  alongside some other hooks to do autopep8 on each commit.
-
-.. include:: ../hooks/leap-commit-template.README
-   :literal:
-
-Dependencies
-----------------------------------
-
-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 ``pkg/requirements.pip``).
-
-
-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' -"
-
-Merging code
----------------------------------
-
-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  
+Bitmask VPN needs administrative privileges. For developing, you
+need to be sure that you have :ref:`installed the privileged helpers
+<privileges>` and that you keep them udpated.
 
 
-Making a new release
---------------------
+Contributing
+------------
 
-A checklist for the release process can be found :ref:`here <release>`
+There are some :ref:`guidelines for contributing code <contributing>` that you
+might want to check if you are insterested in developing with Bitmask.
 
-As part of the release we also tag upload snapshots of the ``leap.bitmask_js``
-package, in order to allow installation of the javascript application without
-needing to compile the javascript and html assets. This is done with::
 
-   cd ui
-   make dist-build
+Release
+-------
 
-and then you can upload it to pypi::
+We keep a :ref:`checklist <release-checklist>` for the release process.
 
-   make dist-upload
 
-Contribution ideas
-------------------
+Ideas
+-----
 
-Want to help? Come talk to us on irc or the mailing list!
+Want to help, but you don't know where to start? Come talk to us on irc or the
+mailing list!
 
 Some areas in which we always need contribution are: