[docs] improve readme

Adds some installation and build instructions.

- Resolves: #35

3 files changed, 115 insertions, 50 deletions

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
new file mode 100644
index 0000000..3d056e3
--- /dev/null
+++ b/CHANGELOG.rst
@@ -0,0 +1,21 @@
+Changelog for Bitmask Lite/RiseupVPN
+====================================
+
+0.18.10 - `master`_
+--------------------
+
+.. note:: This version is not yet released and is under active development.
+
+Bugfixes
+~~~~~~~~
+- `riseupvpn/#31 <https://0xacab.org/leap/riseup_vpn/issues/31>`_: Workaround for desktop entry not showing up on debian.
+- `bitmask-systray/#72 <https://0xacab.org/leap/bitmask-systray/issues/72>`_: Fix gateway selection by timezone.
+- vendor getlantern/systray library.
+
+
+0.18.9
+--------------------
+
+- Initial release (windows, osx and snap packages).
+
+.. _`master`: https://0xacab.org/leap/riseup_vpn
diff --git a/README.rst b/README.rst
index 4408627..d792dcf 100644
--- a/README.rst
+++ b/README.rst
@@ -3,38 +3,107 @@ RiseupVPN
 
 Anonymous VPN. Easy, fast, secure.
 
-This repo has everything needed to build RiseupVPN on different platforms
-(windows, mac, linux).
+This repo has everything needed to build BitmaskLite/RiseupVPN on different platforms
+(windows, mac and linux).
 
-RiseupVPN is a branded build of Bitmask Lite, written in go.
+RiseupVPN is a branded build of Bitmask Lite. Bitmask Lite is a minimal rewrite of the Bitmask VPN Client, written in golang, that for now lacks client authentication, and is preconfigured to use a single provider. As of this moment, it is built for a single provider (riseup.net), but it should be easy to customize for other providers.
 
 
-Dependencies
+Install
 ------------
 
+Linux
+~~~~~
+
+For GNU/Linux, RiseupVPN is distributed using snap. You can get the stable version of the snap from the `snap store` if you're using Gnome Software, that has desktop integration for snaps. Otherwise, you can use the terminal::
+
+  sudo apt install snapd
+  sudo snap install riseup-vpn --classic
+
+After that, you *should* have a RiseupVPN entry in your menu. You can also launch the snap from a terminal::
+  snap run riseup-vpn
+
+Testing other releases of the snap under Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To install a snap published on a specific channel, indicate it from the commandline::
+
+  sudo snap install riseup-vpn --classic --candidate
+  sudo snap install riseup-vpn --classic --beta
+  sudo snap install riseup-vpn --classic --edge
+
+The beta channel has four daily builds of whatever is in the master branch, for amd64 and i686. The edge channel usually contains fixes that we push to be tested individually.
+
+If you are installing a local build of the snap, you need to add the ``--dangerous`` flag::
+
+  sudo snap install riseupvpn --dangerous --classic riseup-vpn*.snap
+
+
+Windows
+~~~~~~~
+
+We build a windows installer for RiseupVPN, using nsis. For testing, you can find the `snap artifact`_ for the latest build in the master branch in the CI. We publish the `latest stable windows installer`_, as well as `windows pre-releases`_.
+
+.. _`snap artifact`: https://0xacab.org/leap/bitmask-systray/-/jobs/artifacts/master/download?job=win_installer
+.. _`latest stable windows installer`: https://downloads.leap.se/RiseupVPN/windows/RiseupVPN-win-latest.exe
+.. _`windows pre-releases`: https://downloads.leap.se/RiseupVPN/windows/beta/
+
+OSX
+~~~
+
+For OSX there is also a `.pkg` installer. You can always get the `latest stable OSX installer`_, as well as `osx pre-releases`_.
+
+.. _`latest stable OSX installer`: https://downloads.leap.se/RiseupVPN/osx/RiseupVPN-OSX-latest.pkg
+.. _`osx pre-releases`: https://downloads.leap.se/RiseupVPN/osx/beta/
+
+Bugs
+------------
+You can report issues in `our bug tracker`_.
+
+.. _`our bug tracker`: https://0xacab.org/leap/riseup_vpn/issues
+
+Build
+------------
+
+If you want to build RiseupVPN yourself, get all prerequisites, using your system's package manager if you wish::
+
 * golang
 * make
-* python (python3, for build scripts)
+* python3
+
+Snap
+~~~~
+
+You can build a local version of the snap::
+
+  make build_snap
+
+OSX
+~~~
+
+To build RiseupVPN in OSX::
+
+  make build_osx
+
+Windows builds
+~~~~~~~~~~~~~~
 
-Dependencies (Windows)
-------------------------
+In *windows* there are a couple of extra dependencies. We recommend using chocolatey to get them::
 
 * nsis
 * nssm
 
-Building (Windows)
-------------------
+You can do a native build in windows::
 
-make deps_win
-make openvpn_win
-make build_win
+  make deps_win
+  make openvpn_win
+  make build_win
 
-Cross-compiling openvpn for windows
------------------------------------
+You can also cross-compile openvpn::
 
-# TODO - modify to build statically and with polarssl.
+  # TODO - modify to build statically and with polarssl.
 
-apt install gcc-mingw-w64-x86-64
-git clone https://github.com/OpenVPN/openvpn-build
-cd openvpn-build/windows-nsis
-CHOST=x86_64-w64-mingw32 CBUILD=i686-pc-cygwin ./build
+  apt install gcc-mingw-w64-x86-64
+  git clone https://github.com/OpenVPN/openvpn-build
+  cd openvpn-build/windows-nsis
+  CHOST=x86_64-w64-mingw32 CBUILD=i686-pc-cygwin ./build
diff --git a/snap/README.rst b/snap/release.rst
index 5e01908..5211aea 100644
--- a/snap/README.rst
+++ b/snap/release.rst
@@ -1,30 +1,14 @@
-RiseupVPN
----------
-
-This is the Snap package for RiseupVPN. RiseupVPN is a specialized build of
-bitmask, that lacks client authentication and is preconfigured to use a single
-provider (riseup.net).
-
-This snap is built using bitmask-systray with the -standalone flag.
-
-Building
----------
-
-First of all, make sure that the version in the snapcraft.yaml file matches what we're building.
-We're following the convention of adding +git to any build that comes after a tag.
+Automatic builds (snap)
+~~~~~~~~~~~~~~~~~~~~~~~
+Gitlab builds snap for amd64 for every push to master in bitmask-systray.
 
 Launchpad does up 4 daily builds if code is modified in bitmask-dev repo. We're
-building for amd64, i386 and arm8.
+building for amd64 and i386. They are pushed to beta channel in the snap store.
 If you need to force a build, trigger it by editing the version string in the
 snapcraft.yaml file.
 
-For local builds, you can use 'make snap_in_docker'. This builds in a docker
-container (provided by snapcraft/snapcore). At this moment, this image is based
-in xenial - therefore, a special tag is needed for the gtk3 libs in go.
-
-
-Releasing
----------
+Releasing snaps
+----------------
 
 From the snap dashboard, you can see the revisions that are built.
 By default, we have riseupvpn-builds configured to upload builds to beta and
@@ -73,12 +57,3 @@ From the command line:
   snapcraft release riseupv-vpn 19 beta
   snapcraft release riseupv-vpn 19 edge
 
-
-Testing
--------
-
-To install a snap published on a specific channel, indicate the channel from the commandline:
-
-  snap install riseup-vpn --classic --edge
-  snap install riseup-vpn --classic --beta
-  snap install riseup-vpn --classic --candidate