diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 28 | ||||
| -rw-r--r-- | docs/dev/workflow.rst | 32 | ||||
| -rw-r--r-- | docs/release_checklist.wiki | 26 | ||||
| -rw-r--r-- | docs/testers/howto.rst | 132 | ||||
| -rw-r--r-- | docs/user/install.rst | 13 |
5 files changed, 180 insertions, 51 deletions
diff --git a/docs/conf.py b/docs/conf.py index 3c908b2c..3cfd0b5d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,7 +11,33 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import sys +import os + + +class Mock(object): + def __init__(self, *args, **kwargs): + pass + + def __call__(self, *args, **kwargs): + return Mock() + + @classmethod + def __getattr__(cls, name): + if name in ('__file__', '__path__'): + return '/dev/null' + elif name[0] == name[0].upper(): + mockType = type(name, (), {}) + mockType.__module__ = __name__ + return mockType + else: + return Mock() + +MOCK_MODULES = ['pysqlite', 'pyopenssl', 'pycryptopp', 'pysqlcipher'] + #'google.protobuf' + +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = Mock() # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst index 1e3bd4af..abd228c1 100644 --- a/docs/dev/workflow.rst +++ b/docs/dev/workflow.rst @@ -27,11 +27,14 @@ Git flow -------- 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 +.. image:: https://downloads.leap.se/pics/git-branching-model.png -The author of the aforementioned post has also a handy pdf version of it: `branching_model.pdf`_ +Vincent Driessen, 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. +However, we use a slightly modified 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`_. @@ -50,30 +53,33 @@ All code ready to be merged into the integration branch is expected to: 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: +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` +``bug/some_descriptive_text`` or -`feature/some_descriptive_text` +``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. +Do your work there, push it, and create a pull request against the develop branch in the main repo (the one owned by leapcode). Now you should wait until we see it, or you can try also posting your pull request in ``#leap-dev`` at `freenode <https://freenode.net>`_. -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: +Your code will get reviewed/discussed by someone else on the team. In case that you need to make some changes, you would do the following:: git checkout <your branch> - # edit what you need here ... +*Edit what you need here ...* + +Simple commit, this doesn't need a good commit message:: - # 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) +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 +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. diff --git a/docs/release_checklist.wiki b/docs/release_checklist.wiki index 19a19289..fc99fdf0 100644 --- a/docs/release_checklist.wiki +++ b/docs/release_checklist.wiki @@ -12,23 +12,27 @@ * [ ] 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/* + * [ ] Update relnotes.txt in leap.bitmask if needed. + * [ ] 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 + - See whatever has been introduced in changes/VERSION_COMPAT + - Reset changes/VERSION_COMPAT * [ ] git commit -av # we should add a commit message here... - * [ ] git checkout master && git pull origin master && git merge --no-ff release-X.Y.Z && git push origin master - * [ ] git tag -s X.Y.Z -m "Tag <package> version X.Y.Z" # (note the -s so that it's a signed tag and -m to specify the message for the tag) - * [ ] git push origin X.Y.Z + + * [ ] 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 + * [ ] git rm changes/feature*; git rm changes/bug* + * [ ] git commit -m "Fold in changes." + + * [ ] git checkout master && git pull origin master && git merge --no-ff release-X.Y.Z --no-edit + * [ ] git tag -s X.Y.Z -m "Tag <package> version X.Y.Z" # (note the -s so that it's a signed tag and -m to specify the message for the tag) + * [ ] git push origin master; git push origin X.Y.Z * [ ] git checkout develop && git merge master && git push origin develop * [ ] Build and upload bundles * [ ] Use the scripts under pkg/<os>/ to build the the bundles. * [ ] Sign them with gpg -a --sign --detach-sign <path/to/bundle> - * [ ] Upload bundle and signature to web-uploads@salmon.leap.se:~/public/client/<os>/Bitmask-<os>-<ver>.(tar.bz2,dmg,zip) + * [ ] Upload bundle and signature to downloads.leap.se/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 diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 61d38787..1e276f7d 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -5,34 +5,125 @@ Howto for Testers This document covers a how-to guide to: -#. Quickly fetching latest development code, and -#. Reporting bugs. +#. :ref:`Where and how report bugs for Bitmask <reporting_bugs>`, and +#. :ref:`Quickly fetching latest development code <fetchinglatest>`. Let's go! +.. _reporting_bugs: + +Reporting bugs +-------------- + +Report all the bugs you can find to us! If something is not quite working yet, +we really want to know. Reporting a bug to us is the best way to get it fixed +quickly, and get our unconditional gratitude. + +It is quick, easy, and probably the best way to contribute to Bitmask +development, other than submitting patches. + +.. admonition:: Reporting better bugs + + New to bug reporting? Here you have a `great document about this noble art + <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_. + +Where to report bugs +^^^^^^^^^^^^^^^^^^^^ + +We use the `Bitmask Bug Tracker <https://leap.se/code/projects/eip-client>`_, +although you can also use `Github issues +<https://github.com/leapcode/bitmask_client/issues>`_. But we reaaaally prefer if you +sign up in the former to send your bugs our way. + +What to include in your bug report +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The symptoms of the bug itself: what went wrong? What items appear broken, or + do not work as expected? Maybe an UI element that appears to freeze? +* The Bitmask version you are running. You can get it by doing `bitmask + --version`, or you can go to `Help -> About Bitmask` menu. +* The installation method you used: bundle? from source code? debian package? +* Your platform version and other details: Ubuntu 12.04? Debian unstable? + Windows 8? OSX 10.8.4? If relevant, your desktop system also (gnome, kde...) +* When does the bug appear? What actions trigger it? Does it always + happen, or is it sporadic? +* The exact error message, if any. +* Attachments of the log files, if possible (see section below). + +Also, try not to mix several issues in your bug report. If you are finding +several problems, it's better to issue a separate bug report for each one of +them. + +Attaching log files +^^^^^^^^^^^^^^^^^^^ + +If you can spend a little time getting them, please add some logs to the bug +report. They are **really** useful when it comes to debug a problem. To do it: + +Launch Bitmask in debug mode. Logs are way more verbose that way:: + + bitmask --debug + +Get your hand on the logs. You can achieve that either by clicking on the "Show +log" button, and saving to file, or directly by specifying the path to the +logfile in the command line invocation:: + + bitmask --debug --logfile /tmp/bitmask.log + +Attach the logfile to your bug report. + +Need human interaction? +^^^^^^^^^^^^^^^^^^^^^^^ + +You can also find us in the ``#leap-dev`` channel on the `freenode network +<https://freenode.net>`_. If you do not have a IRC client at hand, you can +`enter the channel via web +<http://webchat.freenode.net/?nick=leaper....&channels=%23leap-dev&uio=d4>`_. + + .. _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 <environment>` section, only that in a more compact way suitable (ahem) also for non developers. +Normally, testing the latest :ref:`client bundles <standalone-bundle>` should be +enough. We are engaged in a two-week release cycle with minor releases that are +as stable as possible. + +However, if you want to test that some issue has *really* been fixed before the +next release is out (if you are testing a new provider, for instance), you are +encouraged to try out the latest in the development branch. If you do not know +how to do that, or you prefer an automated script, keep reading for a way to +painlessly fetch the latest development code. + +We have put together a script to allow rapid testing in different platforms for +the brave souls like you. It more or less does all the steps covered in the +:ref:`Setting up a Work Enviroment <environment>` section, only that in a more +compact way suitable (ahem) also for non developers. .. note:: - In the near future, we will be using :ref:`standalone bundles <standalone-bundle>` with the ability to self-update. + At some point in the near future, we will be using :ref:`standalone bundles + <standalone-bundle>` with the ability to self-update. Install dependencies ^^^^^^^^^^^^^^^^^^^^ -First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions:: +First, install all the base dependencies plus git, virtualenv and development +files needed to compile several extensions:: apt-get install openvpn git-core python-dev python-pyside python-setuptools python-virtualenv -.. TODO Should review these dependencies. ^^ +.. TODO Should review these dependencies. I think python-sqlite is missing, we + have an issue for that^^ + +.. TODO we really should keep the dependencies in a single file that we are able to + include, to avoid phasing out. + Bootstrap script ^^^^^^^^^^^^^^^^ .. 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. + 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 an improved script. .. note:: This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/ @@ -47,15 +138,22 @@ Download and source the following script in the parent folder where you want you Tada! If everything went well, you should be able to run bitmask by typing:: - bitmask + bitmask --debug 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 (*bitmask-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:: +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:: $ source bin/activate @@ -87,11 +185,11 @@ You should be able to cd into the downloaded repo and pull latest changes:: (bitmask-testbuild)$ cd src/bitmask (bitmask-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. +However, you are encouraged to run the whole bootstrapping process from time to time to help us catching install and versioning 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! +When we have a release candidate for the supported platforms, we will announce also the URI where you can download the rc for testing in your system. Stay tuned! Testing the status of translations ---------------------------------- @@ -104,13 +202,3 @@ If you want to check the current status of bitmask localization in a language ot for running Bitmask with the spanish locales. -Reporting bugs --------------- - -.. admonition:: Reporting better bugs - - There is a great text on the art of bug reporting, that can be found `online <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_. - -.. TODO add a line with ref. to running Bitmask in debug mode... - -We use the `Bitmask Bug Tracker <https://leap.se/code/projects/eip-client>`_, although you can also use `Github issues <https://github.com/leapcode/bitmask/issues>`_. diff --git a/docs/user/install.rst b/docs/user/install.rst index e5765302..bcac4883 100644 --- a/docs/user/install.rst +++ b/docs/user/install.rst @@ -88,14 +88,19 @@ Installing Bitmask is as simple as using `pip <http://www.pip-installer.org/>`_ Show me the code! ----------------- -You can get the code from LEAP public git repository :: +For the users that can find their way through python packages, +you can get the code from LEAP public git repository :: - $ git clone git://leap.se/bitmask_client + $ git clone https://leap.se/git/bitmask_client Or from the github mirror :: $ git clone git://github.com/leapcode/bitmask_client.git -Once you have grabbed a copy of the sources, you can install it into your site-packages easily :: +Once you have grabbed a copy of the sources, and installed all the base +dependencies, you can install it into your site-packages easily :: - $ pyton setup.py install + $ make # compile the resources + $ sudo python2 setup.py install + +Although, like always, it is a better idea to install things in a virtualenv. |