From 5c0eb246d468454de9e84dca0d08c813459a5a6d Mon Sep 17 00:00:00 2001 From: kali Date: Wed, 19 Dec 2012 07:45:02 +0900 Subject: documentation update! reSTructured (no pun intended) the sphinx docs, and trimmed README --- docs/testers/howto.rst | 143 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/testers/howto.rst (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst new file mode 100644 index 00000000..f46711b4 --- /dev/null +++ b/docs/testers/howto.rst @@ -0,0 +1,143 @@ +.. _testhowto: + +Howto for Testers +================= + +This document covers a how-to guide to: + +#. Quickly fetching latest development code, and +#. Reporting bugs. + +Let's go! + +.. _fetchinglatest: + +Fetching latest development code +--------------------------------- + +To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the :ref:`Setting up a Work Enviroment ` section, only that in a more compact way suitable (ahem) also for non developers. + +Install dependencies +^^^^^^^^^^^^^^^^^^^^ +First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions:: + + apt-get install openvpn git-core libgnutls-dev python-dev python-qt4 python-setuptools python-virtualenv + + +Bootstrap script +^^^^^^^^^^^^^^^^ +.. note:: getting latest version of this script. + At some moment we will publish an url from where you can download this script. For now, you can copy and paste this. + +.. note:: + This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script. + +Then copy and paste this script somewhere in your path, in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/leap_client_bootstrap`: + +.. code-block:: bash + :linenos: + + #!/bin/bash + + # Installs requirements, and + # clones the latest leap-client + + # depends on: + # openvpn git-core libgnutls-dev python-dev python-qt4 python-setuptools python-virtualenv + + # Escape code + esc=`echo -en "\033"` + + # Set colors + cc_green="${esc}[0;32m" + cc_yellow="${esc}[0;33m" + cc_blue="${esc}[0;34m" + cc_red="${esc}[0;31m" + cc_normal=`echo -en "${esc}[m\017"` + + echo "${cc_yellow}" + echo "~~~~~~~~~~~~~~~~~~~~~~" + echo "LEAP " + echo "client bootstrapping " + echo "~~~~~~~~~~~~~~~~~~~~~~" + echo "" + echo "${cc_green}Creating virtualenv...${cc_normal}" + + mkdir leap-client-testbuild + virtualenv leap-client-testbuild + source leap-client-testbuild/bin/activate + + echo "${cc_green}Installing leap client...${cc_normal}" + + # Clone latest git (develop branch) + # change "develop" for any other branch you want. + + + pip install -e 'git://leap.se/leap_client@develop#egg=leap-client' + + cd leap-client-testbuild + + # symlink the pyqt libraries to the system libs + ./src/leap-client/pkg/postmkvenv.sh + + echo "${cc_green}leap-client installed! =)" + echo "${cc_yellow}" + echo "Launch it with: " + echo "~~~~~~~~~~~~~~~~~~~~~~" + echo "bin/leap-client" + echo "~~~~~~~~~~~~~~~~~~~~~~" + echo "${cc_normal}" + +and then source it:: + + $ cd /tmp + $ source leap_client_bootstrap + +Tada! If everything went well, you should be able to run the client by typing:: + + bin/leap-client + +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). + +Thus, if you forget to *activate your virtualenv*, the client 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:: + + $ source bin/activate + +from the directory where you *sourced* the bootstrap script. + +Refer to :ref:`Using virtualenv ` to learn more about virtualenv. + +Config files +^^^^^^^^^^^^ + +If you want to start fresh without config files, just move them. In linux:: + + $ mv ~/.config/leap ~/.config/leap.old + +Pulling latest changes +^^^^^^^^^^^^^^^^^^^^^^ + +You should be able to cd into the downloaded repo and pull latest changes:: + + (leap-client-testbuild)$ cd src/leap-client + (leap-client-testbuild)$ git pull origin develop + +However, as a tester you are encouraged to run the whole bootstrap process from time to time to help us catching install and versioniing bugs too. + +Testing the packages +^^^^^^^^^^^^^^^^^^^^ +When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned! + + +Reporting bugs +-------------- + +.. admonition:: Reporting better bugs + + There is a great text on the art of bug reporting, that can be found `online `_. + +We use the `LEAP Client Bug Tracker `_, although you can also use `Github issues `_. -- cgit v1.2.3 From 41a084823ebc967fcabb613a97e8d72c662dbe18 Mon Sep 17 00:00:00 2001 From: kali Date: Wed, 19 Dec 2012 09:38:42 +0900 Subject: added transifex config, updated some docs --- docs/testers/howto.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index f46711b4..6212ed72 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -27,11 +27,15 @@ First, install all the base dependencies plus git, virtualenv and development fi Bootstrap script ^^^^^^^^^^^^^^^^ .. note:: getting latest version of this script. + At some moment we will publish an url from where you can download this script. For now, you can copy and paste this. .. note:: This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script. +.. note:: + This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/ + Then copy and paste this script somewhere in your path, in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/leap_client_bootstrap`: .. code-block:: bash @@ -109,7 +113,12 @@ Thus, if you forget to *activate your virtualenv*, the client will not run from from the directory where you *sourced* the bootstrap script. -Refer to :ref:`Using virtualenv ` to learn more about virtualenv. +Refer to :ref:`Working with virtualenv ` to learn more about virtualenv. + +Policy files +^^^^^^^^^^^^ + +If you have never installed the ``leap-client`` globally, **you need to copy a policykit file to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See :ref:`running openvpn without root privileges ` section for more info on this. Config files ^^^^^^^^^^^^ -- cgit v1.2.3 From 0bb7a486ae2aaf8171afcbe6a9846cbd5a99e0a5 Mon Sep 17 00:00:00 2001 From: kali Date: Wed, 19 Dec 2012 23:55:03 +0900 Subject: fix links to online docs --- docs/testers/howto.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 6212ed72..8de4a1eb 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -149,4 +149,6 @@ Reporting bugs There is a great text on the art of bug reporting, that can be found `online `_. +.. TODO add a line with ref. to running the client in debug mode... + We use the `LEAP Client Bug Tracker `_, although you can also use `Github issues `_. -- cgit v1.2.3 From 06bccc52c84a93407ab4699a2749b24f55fe3061 Mon Sep 17 00:00:00 2001 From: kali Date: Thu, 20 Dec 2012 08:19:55 +0900 Subject: working transifex workflow Closes #666 --- docs/testers/howto.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 8de4a1eb..e5bf1fa8 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -141,6 +141,16 @@ Testing the packages ^^^^^^^^^^^^^^^^^^^^ When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned! +Testing the status of translations +---------------------------------- + +We need translators! You can go to `transifex `_, get an account and start contributing. + +If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do:: + + $ lang=es_ES leap-client + +for running LEAP Client with the spanish locales. Reporting bugs -------------- -- cgit v1.2.3 From 1278ac2aad2de739e164b76c8533bdc7d9679fd6 Mon Sep 17 00:00:00 2001 From: kali Date: Wed, 2 Jan 2013 18:11:18 +0900 Subject: remote source for bootstrap script --- docs/testers/howto.rst | 65 ++++---------------------------------------------- 1 file changed, 4 insertions(+), 61 deletions(-) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index e5bf1fa8..aabcb2b0 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -26,76 +26,19 @@ First, install all the base dependencies plus git, virtualenv and development fi Bootstrap script ^^^^^^^^^^^^^^^^ -.. note:: getting latest version of this script. - - At some moment we will publish an url from where you can download this script. For now, you can copy and paste this. - .. note:: This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script. .. note:: This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/ -Then copy and paste this script somewhere in your path, in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/leap_client_bootstrap`: +Download and source the following script in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/`: .. code-block:: bash - :linenos: - - #!/bin/bash - - # Installs requirements, and - # clones the latest leap-client - - # depends on: - # openvpn git-core libgnutls-dev python-dev python-qt4 python-setuptools python-virtualenv - - # Escape code - esc=`echo -en "\033"` - - # Set colors - cc_green="${esc}[0;32m" - cc_yellow="${esc}[0;33m" - cc_blue="${esc}[0;34m" - cc_red="${esc}[0;31m" - cc_normal=`echo -en "${esc}[m\017"` - - echo "${cc_yellow}" - echo "~~~~~~~~~~~~~~~~~~~~~~" - echo "LEAP " - echo "client bootstrapping " - echo "~~~~~~~~~~~~~~~~~~~~~~" - echo "" - echo "${cc_green}Creating virtualenv...${cc_normal}" - - mkdir leap-client-testbuild - virtualenv leap-client-testbuild - source leap-client-testbuild/bin/activate - - echo "${cc_green}Installing leap client...${cc_normal}" - - # Clone latest git (develop branch) - # change "develop" for any other branch you want. - - - pip install -e 'git://leap.se/leap_client@develop#egg=leap-client' - - cd leap-client-testbuild - - # symlink the pyqt libraries to the system libs - ./src/leap-client/pkg/postmkvenv.sh - - echo "${cc_green}leap-client installed! =)" - echo "${cc_yellow}" - echo "Launch it with: " - echo "~~~~~~~~~~~~~~~~~~~~~~" - echo "bin/leap-client" - echo "~~~~~~~~~~~~~~~~~~~~~~" - echo "${cc_normal}" - -and then source it:: - $ cd /tmp - $ source leap_client_bootstrap + $ cd /tmp + $ wget https://raw.github.com/leapcode/leap_client/develop/pkg/scripts/leap_client_bootstrap.sh + $ source leap_client_bootstrap.sh Tada! If everything went well, you should be able to run the client by typing:: -- cgit v1.2.3 From 656419216f15bfb1859ba850d2d9c9d143034e23 Mon Sep 17 00:00:00 2001 From: kali Date: Tue, 8 Jan 2013 00:32:21 +0900 Subject: doc polishing --- docs/testers/howto.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index aabcb2b0..31e12419 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -36,9 +36,9 @@ 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/leap_client/develop/pkg/scripts/leap_client_bootstrap.sh - $ source leap_client_bootstrap.sh + cd /tmp + wget https://raw.github.com/leapcode/leap_client/develop/pkg/scripts/leap_client_bootstrap.sh + source leap_client_bootstrap.sh Tada! If everything went well, you should be able to run the client by typing:: @@ -68,7 +68,7 @@ Config files If you want to start fresh without config files, just move them. In linux:: - $ mv ~/.config/leap ~/.config/leap.old + mv ~/.config/leap ~/.config/leap.old Pulling latest changes ^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.3 From 88159d703e9b75d3cb0c192e7d7ae92d9d8c67bc Mon Sep 17 00:00:00 2001 From: kali Date: Thu, 24 Jan 2013 03:29:21 +0900 Subject: update docs about system files --- docs/testers/howto.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 31e12419..9b55154f 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -58,13 +58,17 @@ from the directory where you *sourced* the bootstrap script. Refer to :ref:`Working with virtualenv ` to learn more about virtualenv. -Policy files -^^^^^^^^^^^^ +Copying config files +^^^^^^^^^^^^^^^^^^^^ + +If you have never installed the ``leap-client`` globally, **you need to copy some files to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See :ref:`copy script files ` and :ref:`running openvpn without root privileges ` sections for more info on this. In short:: -If you have never installed the ``leap-client`` globally, **you need to copy a policykit file to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See :ref:`running openvpn without root privileges ` section for more info on this. + $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + $ sudo mkdir -p /etc/leap + $ sudo cp pkg/linux/resolv-update /etc/leap -Config files -^^^^^^^^^^^^ +Local config files +^^^^^^^^^^^^^^^^^^^ If you want to start fresh without config files, just move them. In linux:: -- cgit v1.2.3 From 73b73793d524b795279a697cad12c22a808f5c36 Mon Sep 17 00:00:00 2001 From: kali Date: Thu, 24 Jan 2013 07:56:52 +0900 Subject: update docs --- docs/testers/howto.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/testers') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 9b55154f..c4a928ed 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -21,7 +21,7 @@ Install dependencies ^^^^^^^^^^^^^^^^^^^^ First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions:: - apt-get install openvpn git-core libgnutls-dev python-dev python-qt4 python-setuptools python-virtualenv + apt-get install openvpn git-core python-dev python-qt4 python-setuptools python-virtualenv Bootstrap script -- cgit v1.2.3