diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 1 | ||||
| -rw-r--r-- | docs/checklist_for_leap_client_release.wiki | 45 | ||||
| -rw-r--r-- | docs/conf.py | 37 | ||||
| -rw-r--r-- | docs/dev/workflow.rst | 45 | ||||
| -rw-r--r-- | docs/index.rst | 16 | ||||
| -rw-r--r-- | docs/release_checklist.wiki | 40 | ||||
| -rw-r--r-- | docs/testers/howto.rst | 8 | ||||
| -rw-r--r-- | docs/user/install.rst | 64 | ||||
| -rw-r--r-- | docs/user/intro.rst | 18 | ||||
| -rw-r--r-- | docs/user/leap-color-small.png | bin | 0 -> 10100 bytes | |||
| -rw-r--r-- | docs/user/running.rst | 9 |
11 files changed, 193 insertions, 90 deletions
diff --git a/docs/Makefile b/docs/Makefile index 16aa258b..5c2c4145 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,6 +4,7 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build +#SPHINXBUILD = $(VIRTUAL_ENV)/bin/sphinx-build PAPER = BUILDDIR = _build diff --git a/docs/checklist_for_leap_client_release.wiki b/docs/checklist_for_leap_client_release.wiki deleted file mode 100644 index d3bdf1ee..00000000 --- a/docs/checklist_for_leap_client_release.wiki +++ /dev/null @@ -1,45 +0,0 @@ -= LEAP CLient Release Checklist (*) = - - * [ ] validate rc - * [ ] all rc-critical closed! - * [ ] all bbots green - * [ ] uploaded translations: make translations - * [ ] re-generate pyside resources - - * [ ] update docs - * [ ] CREDITS - * [ ] relnotes.txt - * [ ] docs/known_issues.rst - * [ ] NEWS.rst: Add release name and date to top-most item in NEWS. - - * [ ] change docs/quickstart.rst to point to just the current - leap-client-X.Y.Z.deb binaries and .tar.gz source code files - * [ ] on release/vX.Y.Z branch: git pull - * [ ] git tag X.Y.Z - * [ ] build locally to make sure the release is reporting itself as the - intended version (FIXME!) - * [ ] make sure buildbot is green - * [ ] make sure other people aren't committing at that moment - * [ ] FUTURE: push tag along with some other documentation-only patch (typically to - relnotes.txt) to trigger buildslaves - * [ ] git push --tags official; git push official - * [ ] that will build tarballs - * [ ] make sure buildbot is green (in a parallel universe, he) - * [ ] download tarballs, sign with "gpg -ba -u deadbeef TAR", upload *.asc - * [ ] symlink the release tarball on leap.se downloads page: - /var/www/source/leap-client/releases/ CHANGEME XXX - - * [ ] update news pages. release notes. - * [ ] send out relnotes.txt to internal list. - * [ ] wait ...? - - * [ ] PYPI UPLOAD: with "python ./setup.py sdist upload register" - - * [ ] make an "announcement of new release" on leap.se - * [ ] close the Milestone on the chili Roadmap - * [ ] send out relnotes.txt to: - * [ ] mailing lists... - -notes ------ -(*) this checklist kindly borrowed from tahoe-lafs documentation =) diff --git a/docs/conf.py b/docs/conf.py index 39f17d9b..3c908b2c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# LEAP documentation build configuration file, created by +# Bitmask documentation build configuration file, created by # sphinx-quickstart on Sun Jul 22 18:32:05 2012. # # This file is execfile()d with the current directory set to its containing dir. @@ -18,16 +18,20 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../src')) sys.path.insert(0, os.path.abspath('../src/leap')) -sys.path.insert(0, os.path.abspath('../src/leap/crypto')) -sys.path.insert(0, os.path.abspath('../src/leap/keymanager')) -sys.path.insert(0, os.path.abspath('../src/leap/services')) -sys.path.insert(0, os.path.abspath('../src/leap/services/eip')) -sys.path.insert(0, os.path.abspath('../src/leap/util')) - -sys.path.insert(0, os.path.abspath( - os.path.expanduser( - '~/Virtualenvs/leap-client/local/lib/python2.7/' - 'site-packages/leap/common'))) +sys.path.insert(0, os.path.abspath('../src/leap/bitmask')) +sys.path.insert(0, os.path.abspath('../src/leap/bitmask/crypto')) +sys.path.insert(0, os.path.abspath('../src/leap/bitmask/keymanager')) +sys.path.insert(0, os.path.abspath('../src/leap/bitmask/services')) +sys.path.insert(0, os.path.abspath('../src/leap/bitmask/services/eip')) +sys.path.insert(0, os.path.abspath('../src/leap/bitmask/util')) + +try: + sys.path.insert(0, os.path.abspath( + os.path.expanduser( + '~/Virtualenvs/leap-bitmask/local/lib/python2.7/' + 'site-packages/leap/common'))) +except: + pass # TODO: should add all the virtualenv site-packages to the path # as a workaround, install all in your path. @@ -58,17 +62,18 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'LEAP' -copyright = u'2012, The LEAP Encryption Access Project' +project = u'Bitmask' +copyright = u'2012-2013, The LEAP Encryption Access Project' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.2.1-dev1' +import leap.bitmask +version = leap.bitmask.__short_version__ # The full version, including alpha/beta/rc tags. -release = '0.2.1' +release = leap.bitmask.__version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -128,7 +133,7 @@ html_theme = 'default' # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = "../data/images/leap-color-small.png" +html_logo = "../data/images/mask-small.png" # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst index e36431ff..1e3bd4af 100644 --- a/docs/dev/workflow.rst +++ b/docs/dev/workflow.rst @@ -5,6 +5,11 @@ Development Workflow This section documents the workflow that the LEAP project team follows and expects for the code contributions. +While reading this guide, you should have in mind the two rules of contributing code: + +* The first rule of code contribution is: Nobody will push unreviewed code to the mainline branches. +* The second rule of code contribution is: Nobody will push unreviewed code to the mainline branches. + Code formatting --------------- In one word: `PEP8`_. @@ -24,7 +29,7 @@ We are basing our workflow on what is described in `A successful git branching m .. image:: https://leap.se/code/attachments/13/git-branching-model.png -The author of the aforementioned post has also a handy pdf version of it: `branching_model.pdf`_ +The author of the aforementioned post has also a handy pdf version of it: `branching_model.pdf`_ However, we use a setup in which each developer maintains her own feature branch in her private repo. After a code review, this feature branch is rebased onto the authoritative integration branch. Thus, the leapcode repo in leap.se (mirrored in github) only maintains the master and develop branches. @@ -41,3 +46,41 @@ All code ready to be merged into the integration branch is expected to: * Have tests * Be documented * Pass existing tests: do **run_tests.sh** and **tox -v**. All feature branches are automagically built by our `buildbot farm <http://lemur.leap.se:8010/grid>`_. So please check your branch is green before merging it it to `develop`. Rebasing against the current tip of the integration when possible is preferred in order to keep a clean history. + +Using Github +------------ + +Particularly for the Bitmask client, we are using Github. So you should fork the repo from `github`_ . Depending on what kind of work you are going to do (bug or feature) you should create a branch with the following name: + +`bug/some_descriptive_text` + +or + +`feature/some_descriptive_text` + +Do your work there, push it, and create a pull request against the develop branch in the leapcode owned repo. Either you should post the pull request in `#leap-dev` at `Freenode` or we will just notice it when it's created. + +Your code will get reviewed/discussed by someone else on the team, and say that you need to make some changes. What you would do is the following: + + git checkout <your branch> + + # edit what you need here ... + + # Simple commit, this doesn't need a good commit message + git commit -avm "Fix" + + # This will help you reorder your commits and squash them (so that the + # final commit list has good representative messages) + git rebase -i develop + + # Since you've rewritten your history, you'll need a force push + git push <your remote> +<your branch> + +This will update your pull request automatically, but it won't notify us about the update, so you should add a comment saying so, or re-pingthe reviewer. + +.. _`github`: https://github.com/leapcode/ + +Other methods +------------- + +Feel free to use any other methods like format-patch and mail or whatever method you prefer, although we recommend you follow the same workflow as we do. diff --git a/docs/index.rst b/docs/index.rst index e3078929..d0b0ff22 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,20 @@ -.. LEAP documentation master file, created by +.. Bitmask documentation master file, created by sphinx-quickstart on Sun Jul 22 18:32:05 2012. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -LEAP Client +Bitmask ===================================== -Release v\ |version|. (`Impatient? jump to the` :ref:`Installation <install>` `section!`) +Release v \ |version|. (`Impatient? jump to the` :ref:`Installation <install>` `section!`) .. if you change this paragraph, change it in user/intro too -The **LEAP Encryption Access Project Client** is a :ref:`GPL3 Licensed <gpl3>` multiplatform client, written in python using PySide, that supports the features offered by :ref:`the LEAP Platform <leapplatform>`. Currently is being tested on Linux, support for OSX and Windows will come soon. +**Bitmask** is the multiplatform desktop client for the services offered by :ref:`the LEAP Platform <leapplatform>`. +It is written in python using `PySide`_ and :ref:`licensed under the GPL3 <gpl3>`. +Currently we distribute pre-compiled bundles for Linux and OSX, with Windows +bundles following soon. + +.. _`PySide`: http://qt-project.org/wiki/PySide User Guide ---------- @@ -48,7 +53,6 @@ If you want to contribute to the project, we wrote this for you. .. dev/internals dev/authors dev/todo - dev/workflow Packager Guide --------------- @@ -87,3 +91,5 @@ If you are looking for a reference to specific classes or functions, you are lik :maxdepth: 2 api/leap + + diff --git a/docs/release_checklist.wiki b/docs/release_checklist.wiki new file mode 100644 index 00000000..e6467048 --- /dev/null +++ b/docs/release_checklist.wiki @@ -0,0 +1,40 @@ += Bitmask Release Checklist (*) = + * [ ] Check that all tests are passing! + * [ ] 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) + * [ ] Checkout release-X.Y.Z (locally, never pushed) + * [ ] Fold in changes files into the CHANGELOG + - NOTE: For leap.soledad, the CHANGELOG entries should be divided per package (common, client, server). See older releases for reference. + - Helper bash line: for i in $(ls changes); do cat changes/$i; echo; done + * [ ] Update relnotes.txt if needed. + * [ ] git rm changes/* + * [ ] git commit -av + * [ ] Review pkg/requirements.pip for everything and update if needed (that's why the order). + - See whatever has been introduced in changes/VERSION_COMPAT + - Reset changes/VERSION_COMPAT + * [ ] git tag -s X.Y.Z (note the -s so that it's a signed tag) The message should be something like: Tag <package> version X.Y.Z + * [ ] git push origin X.Y.Z + * [ ] git checkout master && git pull origin master && git merge release-X.Y.Z && git push origin master + * [ ] git checkout develop && git pull origin develop && git merge release-X.Y.Z && git push origin develop + * [ ] Build and upload bundles + * [ ] Use the scripts under pkg/<os>/ to build the the bundles. + * [ ] Sign them with gpg -a <path/to/bundle> + * [ ] Upload bundle and signature to web-uploads@salmon.leap.se:~/public/client/<os>/Bitmask-<os>-<ver>.(tar.bz2,dmg,zip) + * [ ] Update symbolic link for latest upload and signature: + * [ ] ~/public/client/Bitmask-<os>-latest + * [ ] ~/public/client/Bitmask-<os>-latest.asc + * [ ] Announce + * [ ] Mail leap@lists.riseup.net + +Notes +----- +(*) this checklist kindly borrowed from tahoe-lafs documentation =) diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index dde893d1..9c6561ed 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -19,7 +19,7 @@ To allow rapid testing in different platforms, we have put together a quick scri .. note:: - In the near future, we will be using ``standalone bundles`` with the ability to self-update. + In the near future, we will be using :ref:`standalone bundles <standalone-bundle>` with the ability to self-update. Install dependencies ^^^^^^^^^^^^^^^^^^^^ @@ -41,8 +41,8 @@ Download and source the following script in the parent folder where you want you .. code-block:: bash cd /tmp - wget https://raw.github.com/leapcode/bitmask/develop/pkg/scripts/leap_client_bootstrap.sh - source leap_client_bootstrap.sh + wget https://raw.github.com/leapcode/leap_client/develop/pkg/scripts/bitmask_bootstrap.sh + source bitmask_bootstrap.sh Tada! If everything went well, you should be able to run bitmask by typing:: @@ -52,7 +52,7 @@ Noticed that your prompt changed? That was *virtualenv*. Keep reading... Activating the virtualenv ^^^^^^^^^^^^^^^^^^^^^^^^^ -The above bootstrap script has fetched latest code inside a virtualenv, which is an isolated, *virtual* python local environment that avoids messing with your global paths. You will notice you are *inside* a virtualenv because you will see a modified prompt reminding it to you (*leap-client-testbuild* in this case). +The above bootstrap script has fetched latest code inside a virtualenv, which is an isolated, *virtual* python local environment that avoids messing with your global paths. You will notice you are *inside* a virtualenv because you will see a modified prompt reminding it to you (*bitmask-testbuild* in this case). Thus, if you forget to *activate your virtualenv*, bitmask will not run from the local path, and it will be looking for something else in your global path. So, **you have to remember to activate your virtualenv** each time that you open a new shell and want to execute the code you are testing. You can do this by typing:: diff --git a/docs/user/install.rst b/docs/user/install.rst index da1d914c..81807a43 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -4,28 +4,53 @@ Installation ============ This part of the documentation covers the installation of Bitmask. -We assume that you want to get it properly installed before being able to use it. +We assume that you want to get it properly installed before being able to use it. But we can we wrong. +.. _standalone-bundle: + +Standalone bundle +----------------- + +Maybe the quickest way of running Bitmask in your machine is using the standalone bundle. That is the recommended way to use Bitmask for the time being. + +You can get the latest bundles, and their matching signatures at `the downloads page <https://downloads.leap.se/client/>`_. + +Linux +^^^^^ +- `Linux 32 bits bundle`_ (`signature <https://downloads.leap.se/client/linux/Bitmask-linux32-latest.tar.bz2.asc>`_) +- `Linux 64 bits bundle`_ (`signature <https://downloads.leap.se/client/linux/Bitmask-linux64-latest.tar.bz2.asc>`_) + +OSX +^^^ +- `OSX bundle`_ (`signature <https://downloads.leap.se/client/osx/Bitmask-OSX-latest.dmg.asc>`_) + +Windows +^^^^^^^ .. note:: - The recommended way of installing in the near future will be the standalone bundles, but those are not quite ready yet. Methods described in this page assume you are familiar with python code, and you can find your way through the process of dependencies install. You can refer to the sections :ref:`setting up a working environment <environment>` or :ref:`fetching latest code for testing <fetchinglatest>`. + The release of the bundles for Windows is delayed right now. We should resume + producing them shortly, keep tuned. +Signature verification +^^^^^^^^^^^^^^^^^^^^^^ -Distribute & Pip ----------------- +For the signature verification you can use :: -.. warning:: The package in the cheese shop is from the stable, `0.2.0` release, which is now outdated. You are encouraged to install the development version instead. + $ gpg --verify Bitmask-linux64-latest.tar.bz2.asc -Installing Bitmask is as simple as using `pip <http://www.pip-installer.org/>`_ for the already released versions :: +Asuming that you downloaded the linux 64 bits bundle. - $ pip install bitmask +.. _`Linux 64 bits bundle`: https://downloads.leap.se/client/linux/Bitmask-linux64-latest.tar.bz2 +.. _`Linux 32 bits bundle`: https://downloads.leap.se/client/linux/Bitmask-linux32-latest.tar.bz2 +.. _`OSX bundle`: https://downloads.leap.se/client/osx/Bitmask-OSX-latest.dmg +.. _`Windows bundle`: https://downloads.leap.se/client/windows/Bitmask-windows-latest.zip Debian package -------------- .. warning:: - The debian package in the leap repositories is from the stable, `0.2.0` release, which is now outdated. You are encouraged to install the development version instead, + The debian package that you can currently find in the leap repositories is from the stable, `0.2.0` release, which is now outdated. You are encouraged to install the development version or the standalone bundles while we upload the newest packages. First, you need to bootstrap your apt-key:: @@ -44,18 +69,35 @@ And then you can happily install bitmask:: apt-get install bitmask +Distribute & Pip +---------------- + +.. note:: + + The rest of the methods described below in this page assume you are familiar with python code, and you can find your way through the process of dependencies install. For more insight, you can also refer to the sections :ref:`setting up a working environment <environment>` or :ref:`fetching latest code for testing <fetchinglatest>`. + +.. image:: https://pypip.in/v/leap.bitmask/badge.png + :target: https://crate.io/packages/leap.bitmask + + +Installing Bitmask is as simple as using `pip <http://www.pip-installer.org/>`_ for the already released versions :: + + $ pip install leap.bitmask + + Show me the code! ----------------- +.. XXX UPDATE REPO NAMES AS SOON AS #3417 is DONE + You can get the code from LEAP public git repository :: - $ git clone git://leap.se/bitmask + $ git clone git://leap.se/leap_client Or from the github mirror :: - $ git clone git://github.com/leapcode/bitmask.git + $ git clone git://github.com/leapcode/leap_client.git Once you have grabbed a copy of the sources, you can install it into your site-packages easily :: $ pyton setup.py install - diff --git a/docs/user/intro.rst b/docs/user/intro.rst index 22ad9356..b93df12b 100644 --- a/docs/user/intro.rst +++ b/docs/user/intro.rst @@ -6,26 +6,34 @@ Introduction Bitmask ------- .. if yoy change this, change it also in the index.rst -**Bitmask** is a :ref:`GPL3 Licensed <gpl3>` multiplatform client, written in python using PySide, that supports the features offered by :ref:`the LEAP Platform <leapplatform>`. Currently is being tested on Linux, support for OSX and Windows will come soon. +**Bitmask** is the multiplatform desktop client for the services offered by :ref:`the LEAP Platform <leapplatform>`. +It is written in python using `PySide`_ and :ref:`licensed under the GPL3 <gpl3>`. +Currently we distribute pre-compiled bundles for Linux and OSX, with Windows +bundles following soon. Features ^^^^^^^^ Bitmask allows to easily secure communications. -- Provider selection -- User registration +- Provider selection. +- User registration. - Encrypted Internet Proxy support (autoconfigured service using openvpn). +- Encrypted email. Coming soon ^^^^^^^^^^^^ -- Encrypted email +- Encrypted chat. + .. _leapplatform: The LEAP Platform ^^^^^^^^^^^^^^^^^ + +.. image:: leap-color-small.* + The LEAP Provider Platform is the server-side part of LEAP that is run by service providers. It consists of a set of complementary packages and recipes to automate the maintenance of LEAP services in a hardened GNU/Linux environment. Our goal is to make it painless for service providers and ISPs to deploy a secure communications platform. Read `more about the LEAP Platform <https://leap.se/en/technology/platform>`_ or `check out the code <https://github.com/leapcode/leap_platform>`_. @@ -97,5 +105,7 @@ Bitmask is released under the terms of the `GNU GPL version 3`_ or later. .. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt +.. _`PySide`: http://qt-project.org/wiki/PySide + .. ??? include whole version? .. include:: ../COPYING diff --git a/docs/user/leap-color-small.png b/docs/user/leap-color-small.png Binary files differnew file mode 100644 index 00000000..bc9d4e7f --- /dev/null +++ b/docs/user/leap-color-small.png diff --git a/docs/user/running.rst b/docs/user/running.rst index da83e9ef..0a93204c 100644 --- a/docs/user/running.rst +++ b/docs/user/running.rst @@ -3,7 +3,8 @@ Running ================== -This document covers how to launch Bitmask. +This document covers how to launch Bitmask. Also know as, where the magic +happens. Launching Bitmask ----------------- @@ -11,7 +12,7 @@ After a successful installation, there should be a launcher called `bitmask` som % bitmask -The first time you launch it, it should launch the first run wizard that will guide you through the setup of the LEAP Services. +The first time you launch it, it should launch the first run wizard that will guide you through the mostly automatic configuration of the LEAP Services. .. note:: @@ -37,8 +38,8 @@ If you ask for it, you can also have all that debug info in a beautiful file rea .. If you want to increment the level of verbosity passed to openvpn, you can do:: .. $ bitmask --openvpn-verbosity 4 -Options ------------- +I want all the options! +----------------------- To see all the available command line options:: $ bitmask --help |
