summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorKali Kaneko (leap communications) <kali@leap.se>2016-08-30 11:25:27 -0400
committerKali Kaneko (leap communications) <kali@leap.se>2016-08-30 11:25:35 -0400
commita9b4554156bac38cd3ca1162326ce9cf554f9b50 (patch)
tree21dacea8338235181b214fa233f93fdff3c0b022 /docs
parent22eec36ff81ae2ec2b924087ed6253894b92278a (diff)
[pkg] add some relevant docs
Diffstat (limited to 'docs')
-rwxr-xr-xdocs/core_api_contract41
-rwxr-xr-xdocs/leap-autopep8.post-commit.hook15
-rwxr-xr-xdocs/leap-autopep8.post-commit.hook.ADD2
-rw-r--r--docs/leap-commit-template7
-rw-r--r--docs/leap-commit-template.README47
-rwxr-xr-xdocs/leap-flake8.pre-commit.hook7
-rw-r--r--docs/man/bitmask-root.1.rst74
-rw-r--r--docs/man/bitmask.1.rst111
-rw-r--r--docs/release_checklist.wiki90
-rw-r--r--docs/testing-rcs.README35
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.
+