[docs] split development docs

the page was becoming too cluttered.

7 files changed, 241 insertions, 240 deletions

diff --git a/docs/hacking/architecture.rst b/docs/hacking/architecture.rst
new file mode 100644
index 00000000..c1e654ed
--- /dev/null
+++ b/docs/hacking/architecture.rst
@@ -0,0 +1,41 @@
+.. _architecture:
+
+The Bitmask Architecture
+========================
+
+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 :ref:`how to develop for the UI<uidev>`.
+
+
+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
+
+
+What Next?
+----------
+
+Have a look at the contribution guide.
diff --git a/docs/hacking/contributing.rst b/docs/hacking/contributing.rst
new file mode 100644
index 00000000..8d835932
--- /dev/null
+++ b/docs/hacking/contributing.rst
@@ -0,0 +1,60 @@
+:LastChangedDate: $LastChangedDate$
+:LastChangedRevision: $LastChangedRevision$
+:LastChangedBy: $LastChangedBy$
+
+.. _contributing:
+
+Contributing
+============
+
+* 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  
diff --git a/docs/hacking/devenv.rst b/docs/hacking/devenv.rst
new file mode 100644
index 00000000..d7ad4157
--- /dev/null
+++ b/docs/hacking/devenv.rst
@@ -0,0 +1,68 @@
+.. _devenv:
+
+Setting a Development Environment
+=================================
+
+
+Convencience script
+~~~~~~~~~~~~~~~~~~~
+
+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::
+
+  make dev-bootstrap
+
+To activate the freshly created virtualenv the next time, you must use `pew`_::
+
+  pew workon bitmask
+
+.. 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.
+
+.. _`pew`: https://pypi.python.org/pypi/pew
+
+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
+
+What next?
+-----------
+Check out the Bitmask Architecture.
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:
 
diff --git a/docs/hacking/privileges.rst b/docs/hacking/privileges.rst
new file mode 100644
index 00000000..3b63d359
--- /dev/null
+++ b/docs/hacking/privileges.rst
@@ -0,0 +1,24 @@
+.. _privileges:
+
+Privilege handling
+==================
+
+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 
diff --git a/docs/hacking/release.rst b/docs/hacking/release.rst
index 20f7c6eb..aaf5b683 100644
--- a/docs/hacking/release.rst
+++ b/docs/hacking/release.rst
@@ -1,4 +1,4 @@
-.. _release:
+.. _release-checklist:
 
 Bitmask Release Checklist
 =========================
@@ -16,49 +16,29 @@ Version bumps and Tagging
 
 * [ ] Tag everything. Should be done for the following packages, in order:
 * [ ] 1. leap.common
-* [ ] 2. leap.keymanager
 * [ ] 3. leap.soledad
-* [ ] 4. leap.mail
 * [ ] 5. leap.bitmask
 * [ ] 6. leap.mx
 
-* NOTE: It's assumed that origin is the leap.se repo
-
 * [ ] git fetch origin
 * [ ] git tag -l, and see the latest tagged version (unless it's not a minor version bump, in which case, just bump to it)
 * [ ] export version: export RELEASE=0.9.0
-* [ ] git checkout `release/0.9.x`
-- NOTE: the release branch is created when the first release candidate
-  is tagged, after that the bugfixes and features that are meant to be
-  shipped with the specific version that we are targetting are merged in that branch
-* [ ] git checkout -b release/$RELEASE (this is a LOCAL branch, never published).
 * [ ] (maybe) cherry-pick specific commits
 * [ ] (maybe) add special fixes for this release
-
 * [ ] Review pkg/requirements.pip for everything, update if needed (that's why the order).
   - See whatever has been introduced in changes/VERSION_COMPAT
   - Reset changes/VERSION_COMPAT
   - Bump all the leap-requirements altogether.
 * [ ] git commit -am "Update requirements file"
-
-* [ ] Merge changes/next-changelog.rst into the CHANGELOG
-  - NOTE: in leap.soledad, 3 sections (common, client, server).
-* [ ] reset changes/next-changelog.rst
 * [ ] git commit -S -m "[pkg] Update changelog"
-
 * [ ] git tag --sign $RELEASE -m "Tag version $RELEASE"
-
-* If everything went ok, push the changes, and merge back into master&develop:
-* [ ] git checkout release/0.9.x && git merge $RELEASE
-* [ ] git push origin release/0.9.x
-* [ ] git push origin $RELEASE
-* [ ] git checkout master && git pull origin master && git merge --no-edit $RELEASE
-* [ ] git checkout develop && git merge $RELEASE && git push origin develop
+* If everything went ok, push the tag.
+* [ ] cd ui && make dist-build && make dist-upload
 
 Bundles
 -------
-* [ ] Build and upload bundles
-* [ ] Use 'make pyinst-linux' to build bundles.
+* [ ] Build and upload bundles:
+      [ ] make bundle_in_docker
 * [ ] Sign: make pyinst-sign
 * [ ] Upload bundle and signature to downloads.leap.se/client/<os>/Bitmask-<os>-<ver>.(tar.bz2,dmg,zip)
 * [ ] make pyinst-upload
@@ -66,26 +46,10 @@ Bundles
 * [ ] ~/public/client/Bitmask-<os>-latest
 * [ ] ~/public/client/Bitmask-<os>-latest.asc
 
-TUF: Relese candidate bundles: RC# (skipped for now)
-----------------------------------------------------
-
-* [ ] Upload the TUF unstable repo
-* [ ] Upload bundle to staging for release-candidate
-* [ ] Sign the bundles, move it to client downloads (micah)
-* [ ] Update symlinks for -latest
-* [ ] Fix all show stoppers
-
-TUF: Stable bundles (skipped for now)
--------------------------------------
-* [ ] Upload the TUF Stable Repo to staging
-* [ ] Upload bundle to staging for stable
-* [ ] move and sign the TUF repo (kwadro)
-* [ ] Sign the bundles, move it to client downloads (micah)
-* [ ] Update symlinks for -latest
-  
 Debian packages
 ---------------
-* TBD...
+* [ ] update changelog
+* [ ] upload staging packages to release component
 
 Pypi upload
 ---------------
@@ -98,5 +62,3 @@ Announcing
  * [ ] Twitter
  * [ ] Gnusocial
  * [ ] Post in leap.se
- * [ ] reddit
- * [ ] hackernews
diff --git a/docs/hacking/uidev.rst b/docs/hacking/uidev.rst
new file mode 100644
index 00000000..4ada825e
--- /dev/null
+++ b/docs/hacking/uidev.rst
@@ -0,0 +1,6 @@
+.. _uidev:
+
+Bitmask's Javascript User Interface
+====================================
+
+(stuff goes here).