Add R3.1 release notes

qubes-release/README.Qubes-Release-Notes

@@ -1,6 +1,64 @@
-README.Qubes-Release-Notes
+Qubes R3.1 release notes
-==========================
+========================
 
-This is a placeholder. There are no useful release notes in here.
+New features since 3.0
+----------------------
 
-Sorry about that.
+* Management Stack based of Salt Stack in dom0 - [documentation](https://www.qubes-os.org/doc/salt/)
+* Out of the box Whonix setup
+* UEFI support
+* Updated GPU drivers in dom0
+* Colorful window application icons (instead of just colorful lock icon)
+* PV Grub support ([documentation](https://www.qubes-os.org/doc/managing-vm-kernel/#tocAnchor-1-3))
+* Out of the box USB VM setup, including [handling USB mouse](https://github.com/QubesOS/qubes-app-linux-input-proxy/blob/master/README.md)
+* Xen upgraded to 4.6, for better hardware support (especially Skylake platform)
+* Improve updates proxy flexibility - especially repositories served over HTTPS
+
+You can get detailed description in [completed github issues](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+sort%3Aupdated-desc+milestone%3A%22Release+3.1%22+label%3Arelease-notes+is%3Aclosed)
+
+Known issues
+------------
+
+* Installation image does not fit on DVD, requires either DVD DL, or USB stick (5GB or more)
+
+* Windows Tools: `qvm-block` does not work
+
+* Some icons in the Qubes Manager application might not be drawn correctly when using the Xfce4 environment in Dom0. If this bothers you, please use the KDE environment instead.
+
+* USB mouse (in case of USB VM) does not work at first system startup (just after completing firstboot). Workaround: restart the system.
+
+* For other known issues take a look at [our tickets](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22Release+3.1%22+label%3Abug)
+
+It is advised to install updates just after system installation to apply bug fixes for (some of) the above problems.
+
+Downloads
+---------
+
+See [Qubes Downloads](https://www.qubes-os.org/downloads/).
+
+Installation instructions
+-------------------------
+
+See [Installation Guide](https://www.qubes-os.org/doc/installation-guide/).
+
+Upgrading
+---------
+
+### From R3.0
+
+The easiest and safest way to upgrade to Qubes R3.1 is to install it from
+scratch and use [qubes backup and restore tools](https://www.qubes-os.org/doc/backup-restore/) for
+migrating of all of the user VMs.
+
+Users of Qubes R3.0 can upgrade using [this
+procedure](https://www.qubes-os.org/doc/upgrade-to-r3.1/).
+
+### From R2 or earlier
+
+When upgrading from earlier versions the easiest and safest way is to install
+it from scratch and use [qubes backup and restore tools](https://www.qubes-os.org/doc/backup-restore/)
+for migrating of all of the user VMs.
+
+Alternatively you can [upgrade to R3.0
+using](/doc/releases/3.0/release-notes/#upgrading) first, then follow the
+instructions above. This will be time consuming process.