diff options
Diffstat (limited to 'docs/dev')
| -rw-r--r-- | docs/dev/environment.rst | 61 | ||||
| -rw-r--r-- | docs/dev/internals.rst | 2 | ||||
| -rw-r--r-- | docs/dev/internationalization.rst | 40 | ||||
| -rw-r--r-- | docs/dev/resources.rst | 4 | ||||
| -rw-r--r-- | docs/dev/tests.rst | 4 | ||||
| -rw-r--r-- | docs/dev/workflow.rst | 8 |
6 files changed, 61 insertions, 58 deletions
diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst index c3868b81..7ce536f9 100644 --- a/docs/dev/environment.rst +++ b/docs/dev/environment.rst @@ -3,24 +3,25 @@ Setting up a development environment ==================================== -This document covers how to get an enviroment ready to contribute code to the LEAP Client. +This document covers how to get an enviroment ready to contribute code to Bitmask. Cloning the repo ---------------- .. note:: - Stable releases will be in *master* branch (nothing there yet, move on!). + Stable releases are in *master* branch. Development code lives in *develop* branch. :: - git clone git://leap.se/leap_client + git clone git://leap.se/bitmask + git checkout develop Base Dependencies ------------------ -Leap client depends on these libraries: +Bitmask depends on these libraries: * `python 2.6 or 2.7` -* `qt4` libraries (see also :ref:`Troubleshooting PyQt install <pyqtvirtualenv>` about how to install inside your virtualenv) +* `qt4` libraries (see also :ref:`Troubleshooting PySide install <pysidevirtualenv>` about how to install inside your virtualenv) * `openssl` * `openvpn <http://openvpn.net/index.php/open-source/345-openvpn-project.html>`_ @@ -28,7 +29,7 @@ Debian ^^^^^^ In debian-based systems:: - $ apt-get install openvpn python-qt4 python-crypto python-openssl + $ apt-get install openvpn python-pyside python-openssl To install the software from sources:: @@ -50,6 +51,10 @@ The basic problem being addressed is one of dependencies and versions, and indir Read more about it in the `project documentation page <http://pypi.python.org/pypi/virtualenv/>`_. +.. note:: + this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...). We also should document how to use virtualenvwrapper. + + Create and activate your dev environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -58,36 +63,36 @@ Create and activate your dev environment $ virtualenv </path/to/new/environment> $ source </path/to/new/environment>/bin/activate -Install python dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _pysidevirtualenv: -You can install python dependencies with pip. If you do it inside your working environment, they will be installed avoiding the need for administrative permissions:: +Avoid compiling PySide inside a virtualenv +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - $ pip install -r pkg/requirements.pip +If you attempt to install PySide inside a virtualenv as part of the rest of the dependencies using pip, basically it will take ages to compile. -.. _pyqtvirtualenv: +As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PySide installation (*this is the recommended way if you are running a debian-based system*):: -Troubleshooting PyQt install inside a virtualenv -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + $ pkg/postmkvenv.sh -If you attempt to install PyQt inside a virtualenv using pip, it will fail because PyQt4 does not use the standard setup.py mechanism. +A second option if that does not work for you would be to install PySide globally and pass the ``--site-packages`` option when you are creating your virtualenv:: -As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PyQt installation (*this is the recommended way if you are running a debian-based system*):: + $ apt-get install python-pyside + $ virtualenv --site-packages . - $ pkg/postmkvenv.sh +After that, you must export ``LEAP_VENV_SKIP_PYSIDE`` to skip the isntallation:: -A second option if that does not work for you would be to install PyQt globally and pass the ``--site-packages`` option when you are creating your virtualenv:: + $ export LEAP_VENV_SKIP_PYSIDE=1 - $ apt-get install python-qt4 - $ virtualenv --site-packages . +And now you are ready to proceed with the next section. -Or, if you prefer, you can also `download the official PyQt tarball <http://www.riverbankcomputing.com/software/pyqt/download>`_ and execute ``configure.py`` in the root folder of their distribution, which generates a ``Makefile``:: +.. _pydepinstall: - $ python configure.py - $ make && make install +Install python dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: - this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...). +You can install python dependencies with ``pip``. If you do it inside your working environment, they will be installed avoiding the need for administrative permissions:: + + $ pip install -r pkg/requirements.pip .. _copyscriptfiles: @@ -95,10 +100,10 @@ Or, if you prefer, you can also `download the official PyQt tarball <http://www. Copy script files ----------------- -The openvpn invocation expects some files to be in place. If you have not installed `leap-client` from a debian package, you must copy these files manually:: +The openvpn invocation expects some files to be in place. If you have not installed `bitmask` from a debian package, you must copy these files manually by now:: $ sudo mkdir -p /etc/leap - $ sudo cp pkg/linux/resolv-update /etc/leap + $ sudo cp pkg/linux/resolv-update /etc/leap .. _policykit: @@ -106,9 +111,9 @@ Running openvpn without root privileges --------------------------------------- In linux, we are using ``policykit`` to be able to run openvpn without root privileges, and a policy file is needed to be installed for that to be possible. -The setup script tries to install the policy file when installing the client system-wide, so if you have installed the client in your global site-packages at least once it should have copied this file for you. +The setup script tries to install the policy file when installing bitmask system-wide, so if you have installed bitmask in your global site-packages at least once it should have copied this file for you. -If you *only* are running the client from inside a virtualenv, you will need to copy this file by hand:: +If you *only* are running bitmask from inside a virtualenv, you will need to copy this file by hand:: $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ diff --git a/docs/dev/internals.rst b/docs/dev/internals.rst index 8bb19211..e43868f3 100644 --- a/docs/dev/internals.rst +++ b/docs/dev/internals.rst @@ -3,7 +3,7 @@ Internals ========= -This section covers briefly the internal organization of the LEAP Client source tree. +This section covers briefly the internal organization of Bitmask source tree. .. note:: diff --git a/docs/dev/internationalization.rst b/docs/dev/internationalization.rst index 1a9af0be..f9f522b9 100644 --- a/docs/dev/internationalization.rst +++ b/docs/dev/internationalization.rst @@ -3,15 +3,15 @@ Internationalization ==================== -This part of the documentation covers the localization and translation of LEAP Client. +This part of the documentation covers the localization and translation of Bitmask. Because we want to *bring fire to the people*, in as many countries and languages as possible. -Translating the LEAP Client PyQt Application --------------------------------------------- +Translating Bitmask PySide Application +-------------------------------------- .. raw:: html - <div><a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/projects/p/leap-client/resource/leap-client/" title="See more information on Transifex.com">Top translations: leap-client » leap-client</a><br/><img border="0" src="https://www.transifex.com/projects/p/leap-client/resource/leap-client/chart/image_png"/><br/><a target="_blank" href="https://www.transifex.com/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a></div> + <div><a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/projects/p/bitmask/resource/bitmask/" title="See more information on Transifex.com">Top translations: bitmask » bitmask</a><br/><img border="0" src="https://www.transifex.com/projects/p/bitmask/resource/bitmask/chart/image_png"/><br/><a target="_blank" href="https://www.transifex.com/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a></div> For translators @@ -21,7 +21,7 @@ For translators as internal notes. -We are using `transifex <http://transifex.com/projects/p/leap-client>`_ to coordinate translation efforts. If you want to contribute, just sign up there and ... +We are using `transifex <http://transifex.com/projects/p/bitmask>`_ to coordinate translation efforts. If you want to contribute, just sign up there and ... .. note:: ... and what?? @@ -32,7 +32,7 @@ For devs: i18n conventions .. note:: should say something about our special cases (provider labels and exceptions) when we get decision about it. -Refer to `pyqt documentation <http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/i18n.html>`_. +Refer to `pyside documentation <http://qt-project.org/wiki/PySide_Internationalization>`_. tl;dr;:: @@ -40,15 +40,11 @@ tl;dr;:: for any string that you want to be translated, as long as the instance derives from ``QObject``. -If you have to translate something that it is not a ``QObject``, use the magic leap ``translate`` method: - - -.. code-block:: python - - from leap.util.translations import translate - - class Foo(object): - bar = translate(<Context>, <string>, <comment>) +.. If you have to translate something that it is not a ``QObject``, use the magic leap ``translate`` method: +.. .. code-block:: python +.. from leap.util.translations import translate +.. class Foo(object): +.. bar = translate(<Context>, <string>, <comment>) .. Note about this: there seems to be some problems with the .tr method @@ -59,17 +55,17 @@ If you have to translate something that it is not a ``QObject``, use the magic l For i18n maintainers ^^^^^^^^^^^^^^^^^^^^ -You need ``pylupdate4`` and ``lrelease`` for these steps. To get it, in debian:: +You need ``pyside-lupdate`` and ``lrelease`` for these steps. To get it, in debian:: - $ apt-get install pyqt4-dev-tools qt4-linguist-tools + $ apt-get install pyside-tools qt4-linguist-tools If you do not already have it, install the ``transifex-client`` from the cheese shop:: - pip install transifex-client + pip install transifex-client You can learn more about the transifex-client `here <http://help.transifex.com/features/client/index.html>`_. -**1.** Add any new source files to the project file, ``data/leap_client.pro``. *We should automate this with some templating, it's tedious.* +**1.** Add any new source files to the project file, ``data/bitmask.pro``. *We should automate this with some templating, it's tedious.* **2.** Update the source .ts file ``data/ts/en_US.ts``.:: @@ -84,7 +80,7 @@ You can learn more about the transifex-client `here <http://help.transifex.com/f **5.** *Et voila!* Get updated .ts files for each language from ``Transifex``. For instance, to pull updated spanish translations:: $ tx pull -l es - Pulling new translations for resource leap-client.leap-client (source: data/ts/en_US.ts) + Pulling new translations for resource bitmask.bitmask (source: data/ts/en_US.ts) -> es: data/translations/es.ts Done. @@ -93,7 +89,7 @@ Note that there is a configuration option in ``.tx/config`` for setting the mini **6.** Generate .qm files from the updated .ts files:: - $ make translations + $ make translations and yes, it's the same command than in step 2. One less thing to remember :) @@ -105,7 +101,7 @@ and yes, it's the same command than in step 2. One less thing to remember :) If you want to try it, just set your LANG environment variable:: - $ LANG=es_ES leap-client + $ LANG=es_ES bitmask Translating the Documentation diff --git a/docs/dev/resources.rst b/docs/dev/resources.rst index 7cfa2b70..e68649a1 100644 --- a/docs/dev/resources.rst +++ b/docs/dev/resources.rst @@ -1,7 +1,7 @@ .. _resources: -PyQt Resource files -=================== +PySide Resource files +===================== Compiling resource/ui files --------------------------- diff --git a/docs/dev/tests.rst b/docs/dev/tests.rst index 7f5fbaaf..d55c206a 100644 --- a/docs/dev/tests.rst +++ b/docs/dev/tests.rst @@ -39,8 +39,8 @@ Hint: colorized output Install ``rednose`` locally, export the ``NOSE_REDNOSE`` variable, and give your eyes a rest :):: - (leap_client)% pip install rednose - (leap_client)% export NOSE_REDNOSE=1 + (bitmask)% pip install rednose + (bitmask)% export NOSE_REDNOSE=1 Testing all the supported python versions ----------------------------------------- diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst index 5ceccca4..e36431ff 100644 --- a/docs/dev/workflow.rst +++ b/docs/dev/workflow.rst @@ -20,20 +20,22 @@ If you introduce a new dependency, please add it under ``pkg/requirements`` or ` Git flow -------- -See `A successful git branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_ for more information. The slight modification we make is that release tags are made in the release branch before getting merged to master, rather than getting tagged in master. +We are basing our workflow on what is described in `A successful git branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_. .. 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`_ +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. + A couple of tools that help to follow this process are `git-flow`_ and `git-sweep`_. .. _`branching_model.pdf`: https://leap.se/code/attachments/14/Git-branching-model.pdf .. _`git-flow`: https://github.com/nvie/gitflow .. _`git-sweep`: http://pypi.python.org/pypi/git-sweep -Merge into integration branch ------------------------------ +Code review and merges into integration branch +----------------------------------------------- All code ready to be merged into the integration branch is expected to: * Have tests |