diff options
Diffstat (limited to 'docs')
| -rwxr-xr-x | docs/core_api_contract | 41 | ||||
| -rwxr-xr-x | docs/leap-autopep8.post-commit.hook | 15 | ||||
| -rwxr-xr-x | docs/leap-autopep8.post-commit.hook.ADD | 2 | ||||
| -rw-r--r-- | docs/leap-commit-template | 7 | ||||
| -rw-r--r-- | docs/leap-commit-template.README | 47 | ||||
| -rwxr-xr-x | docs/leap-flake8.pre-commit.hook | 7 | ||||
| -rw-r--r-- | docs/man/bitmask-root.1.rst | 74 | ||||
| -rw-r--r-- | docs/man/bitmask.1.rst | 111 | ||||
| -rw-r--r-- | docs/release_checklist.wiki | 90 | ||||
| -rw-r--r-- | docs/testing-rcs.README | 35 |
10 files changed, 429 insertions, 0 deletions
diff --git a/docs/core_api_contract b/docs/core_api_contract new file mode 100755 index 00000000..b70fb8fa --- /dev/null +++ b/docs/core_api_contract @@ -0,0 +1,41 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +# api_contract.py +# Copyright (C) 2016 LEAP Encryption Acess Project +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. +""" +Display a human-readable representation of the methods that compound the public +api for Bitmask Core. + +The values are meant to be type annotations. +""" + +if __name__ == "__main__": + from leap.bitmask.core.service import BitmaskBackend + from leap.bitmask.core import api + backend = BitmaskBackend() + + print '========= Bitmask Core API ==================' + print + + for key in api.registry: + human_key = key.replace('do_', '').lower() + value = api.registry[key] + + print("{}:\t\t{}".format( + human_key, + ' '.join([x for x in value]))) + print + print '=============================================' diff --git a/docs/leap-autopep8.post-commit.hook b/docs/leap-autopep8.post-commit.hook new file mode 100755 index 00000000..cffb1d53 --- /dev/null +++ b/docs/leap-autopep8.post-commit.hook @@ -0,0 +1,15 @@ +#!/bin/sh + +# Auto pep8 correction as a post-commit hook. +# Thanks to http://victorlin.me/posts/2014/02/05/auto-post-commit-pep8-correction + +echo "[+] running autopep8..." +FILES=$(git diff HEAD^ HEAD --name-only --diff-filter=ACM | grep -e '\.py$') + +for f in $FILES +do + # auto pep8 correction + autopep8 --in-place $f +done + +git status diff --git a/docs/leap-autopep8.post-commit.hook.ADD b/docs/leap-autopep8.post-commit.hook.ADD new file mode 100755 index 00000000..b6e07ae5 --- /dev/null +++ b/docs/leap-autopep8.post-commit.hook.ADD @@ -0,0 +1,2 @@ + #!/bin/sh + cd .git/hooks && ln -s ../../docs/leap-autopep8.post-commit.hook post-commit diff --git a/docs/leap-commit-template b/docs/leap-commit-template new file mode 100644 index 00000000..8a5c7cd0 --- /dev/null +++ b/docs/leap-commit-template @@ -0,0 +1,7 @@ +[bug|feat|docs|style|refactor|test|pkg|i18n] ... +... + +- Resolves: #XYZ +- Related: #XYZ +- Documentation: #XYZ +- Releases: XYZ diff --git a/docs/leap-commit-template.README b/docs/leap-commit-template.README new file mode 100644 index 00000000..ce8809e7 --- /dev/null +++ b/docs/leap-commit-template.README @@ -0,0 +1,47 @@ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +HOW TO USE THIS TEMPLATE: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run `git config commit.template docs/leap-commit-template` or +edit the .git/config for this project and add +`template = docs/leap-commit-template` +under the [commit] block + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +COMMIT TEMPLATE FORMAT EXPLAINED +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[type] <subject> + +<body> +<footer> + +Type should be one of the following: +- bug (bug fix) +- feat (new feature) +- docs (changes to documentation) +- style (formatting, pep8 violations, etc; no code change) +- refactor (refactoring production code) +- test (adding missing tests, refactoring tests; no production code change) +- pkg (packaging related changes; no production code change) +- i18n translation related changes + +Subject should use imperative tone and say what you did. +For example, use 'change', NOT 'changed' or 'changes'. + +The body should go into detail about changes made. + +The footer should contain any issue references or actions. +You can use one or several of the following: + +- Resolves: #XYZ +- Related: #XYZ +- Documentation: #XYZ +- Releases: XYZ + +The Documentation field should be included in every new feature commit, and it +should link to an issue in the bug tracker where the new feature is analyzed +and documented. + +For a full example of how to write a good commit message, check out +https://github.com/sparkbox/how_to/tree/master/style/git diff --git a/docs/leap-flake8.pre-commit.hook b/docs/leap-flake8.pre-commit.hook new file mode 100755 index 00000000..b00fd08a --- /dev/null +++ b/docs/leap-flake8.pre-commit.hook @@ -0,0 +1,7 @@ +#!/bin/sh +# Auto-check for pep8 so I don't check in bad code +FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -e '\.py$') + +if [ -n "$FILES" ]; then + flake8 -r $FILES +fi diff --git a/docs/man/bitmask-root.1.rst b/docs/man/bitmask-root.1.rst new file mode 100644 index 00000000..b25a3362 --- /dev/null +++ b/docs/man/bitmask-root.1.rst @@ -0,0 +1,74 @@ +============ +bitmask-root +============ + +------------------------------------------------------------------------ +privileged helper for bitmask, the encrypted internet access toolkit. +------------------------------------------------------------------------ + +:Author: LEAP Encryption Access Project https://leap.se +:Date: 2015-11-03 +:Copyright: GPLv3+ +:Version: 0.9.1 +:Manual section: 1 +:Manual group: General Commands Manual + +SYNOPSIS +======== + +bitmask-root [openvpn | firewall | version] [start | stop | isup] [ARGS] + +DESCRIPTION +=========== + +*bitmask-root* is a privileged helper for bitmask. + +It is used to start or stop openvpn and the bitmask firewall. To operate, it +needs to be executed with root privileges. + + +OPTIONS +======= + +openvpn +-------- + +**start** [ARGS] Starts openvpn. All args are passed to openvpn, and + filtered against a list of allowed args. If the next + argument is `restart`, the firewall will not be torn + down in the case of errors launching openvpn. + +**stop** Stops openvpn. + + +firewall +-------- + +**start** [GATEWAYS] Starts the firewall. GATEWAYS is a list of EIP + gateways to allow in the firewall. + +**stop** Stops the firewall. + +**isup** Check if the firewall is up. + + +fw-email +-------- + +**start** UID Starts the email firewall. UID is the user name or unix + id that will have access to the email. + +**stop** Stops the email firewall. + +**isup** Check if the email firewall is up. + +version +-------- + +**version** Prints the `bitmask-root` version string. + + +BUGS +==== + +Please report any bugs to https://leap.se/code/projects/report-issues diff --git a/docs/man/bitmask.1.rst b/docs/man/bitmask.1.rst new file mode 100644 index 00000000..0970b449 --- /dev/null +++ b/docs/man/bitmask.1.rst @@ -0,0 +1,111 @@ +======= +bitmask +======= + +------------------------------------------------------------------------ +graphical client to control LEAP, the encrypted internet access toolkit. +------------------------------------------------------------------------ + +:Author: The LEAP Encryption Access Project https://leap.se +:Date: 2015-11-03 +:Copyright: GPLv3+ +:Version: 0.9.1 +:Manual section: 1 +:Manual group: General Commands Manual + +SYNOPSIS +======== + +bitmask [-h] [-d] [-l [LOG FILE]] [--openvpn-verbosity [OPENVPN_VERB]] + +DESCRIPTION +=========== + +*bitmask* is a graphical client to control LEAP, the encrypted internet access toolkit. + +When launched, it places an icon in the system tray from where the LEAP services can be controlled. + + +OPTIONS +======= + +general options +--------------- + +**-h, --help** Print a help message and exit. + +**-l, --logfile=<file>** Writes log to file. + +**-s, --standalone** Makes Bitmask use standalone directories for configuration and binary searching. + +**-V, --version** Displays Bitmask version and exits. + + +openvpn options +--------------- + +**--openvpn-verbosity** [0-5] Verbosity level for openvpn logs. + +debug options +------------- +**-d, --debug** Launches client in debug mode, writing debug info to stdout. + +**--danger** Bypasses the certificate check for bootstrap. This open the possibility of MITM attacks, so use only to debug providers in controlled environments, and never in production. + +ENCRYPTED MAIL +============== + +Bitmask now (since version 0.3.0) supports the encrypted mail service with providers that offer it. + +Mail client configuration +------------------------- + +To be able to use the mail services, you should configure your mail client to +talk to the following ports: + +**STMP**: localhost:2013 + +**IMAP**: localhost:1984 + +For the time being, we have successfully tested this functionality in thunderbird. + +Mail poll period +---------------- + +If you want to change the default polling time for fetching mail, you can use +a environment variable: BITMASK_MAILCHECK_PERIOD + +WARNING +======= + +This software is still in its early phases of testing. So don't trust your life to it! + + +FILES +===== + + +/usr/share/polkit-1/actions/se.leap.bitmask.policy +------------------------------------------------------- + +PolicyKit policy file, used for granting access to bitmask-root without the need of entering a password each time. + +/usr/sbin/bitmask-root +------------------------ + +Helper to launch and stop openvpn and the bitmask firewall. + +~/.config/leap/ +--------------- + +Main config folder + +~/.config/leap/leap.conf +------------------------ + +GUI options + +BUGS +==== + +Please report any bugs to https://leap.se/code/projects/report-issues diff --git a/docs/release_checklist.wiki b/docs/release_checklist.wiki new file mode 100644 index 00000000..95ff2204 --- /dev/null +++ b/docs/release_checklist.wiki @@ -0,0 +1,90 @@ += Bitmask Release Checklist = + + == CI check == + * [ ] Check that all tests are passing! + * [ ] Fix any broken tests. + + == Version bumps and Tagging == + * [ ] Update pkg/next-release + * [ ] Update release-notes.rst in leap.bitmask if needed. + * [ ] Update version in bitmask_client/pkg/linux/bitmask-root if needed. + + * [ ] 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 + + == Bundles == + * [ ] Build and upload bundles + * [ ] Use 'make pyinst-linux' to build bundles. + * [ ] Sign: make pyinst-sign + * [ ] Upload bundle and signature to downloads.leap.se/client/<os>/Bitmask-<os>-<ver>.(tar.bz2,dmg,zip) + * [ ] make pyinst-upload + * [ ] Update symbolic link for latest upload and signature: + * [ ] ~/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... + + == Pypi upload == + * [ ] python setup.py sdist upload --sign -i kali@leap.se -r pypi + + == Announcing == + * [ ] Announce (use release-notes.rst) + * [ ] Mail leap@lists.riseup.net + * [ ] Twitter + * [ ] Gnusocial + * [ ] Post in leap.se + * [ ] reddit + * [ ] hackernews diff --git a/docs/testing-rcs.README b/docs/testing-rcs.README new file mode 100644 index 00000000..b0340f0a --- /dev/null +++ b/docs/testing-rcs.README @@ -0,0 +1,35 @@ +Tips for QA +------------ + +From time to time, we'll ask the community for help testing a new alpha release +or a release candidate. Normally, we'll offer a link for the download of a +self-contained bundle just for internal testing purposes. These will be updated +quite often, as soon as there are fixes available to fix the release-critical +bugs. + +If you want to give a hand in this process, please follow the following tips: + +- Focus all your efforts, if possible, on whatever is *the* golden distro at + the time of the release. This currently is: Ubuntu 14.04.x LTS, 64bits, with +Unity as the default desktop environment. + It's very important to have a reference environment as bug-free as possible, + before trying to solve issues that are present in other distributions or window + managers. +- Identify all issues that need help in the QA phase. You can do that going to + the bug tracker, and filtering all the issues for a given release that are in + the QA state. +- If the issue is solved in your tests for this alpha release, please add a + comment to the issue stating the results of your tests, and the platform and + desktop environment in which your tests took place. But please do not change + the QA status on the issue. We generally leave this role to the author of the + original issue, or to the person playing the role of the release QA master. +- Always test with a newly created account (specially relevant when testing + email candidates) +- Always test with the reference Mail User Agent (currently, Thunderbird, in + whatever version is present in the reference distribution). +- Remove also any thunderbird configuration, start a freshly configured account. +- If you find a new bug, please make sure that it hasn't already been reported + in the issue tracker. If you are absolutely certain that you have found a new + bug, please attach a log of a new bitmask session, which should contain + *only* the behaviour needed to reproduce the bug you are reporting. + |