[pkg] add some relevant docs

author: Kali Kaneko (leap communications) <kali@leap.se> 2016-08-30 11:25:27 -0400
committer: Kali Kaneko (leap communications) <kali@leap.se> 2016-08-30 11:25:35 -0400
commit: a9b4554156bac38cd3ca1162326ce9cf554f9b50 (patch)
tree: 21dacea8338235181b214fa233f93fdff3c0b022 /docs
parent: 22eec36ff81ae2ec2b924087ed6253894b92278a (diff)
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.
+
author	Kali Kaneko (leap communications) <kali@leap.se>	2016-08-30 11:25:27 -0400
committer	Kali Kaneko (leap communications) <kali@leap.se>	2016-08-30 11:25:35 -0400
commit	a9b4554156bac38cd3ca1162326ce9cf554f9b50 (patch)
tree	21dacea8338235181b214fa233f93fdff3c0b022 /docs
parent	22eec36ff81ae2ec2b924087ed6253894b92278a (diff)