Merge branch 'master' of github.com:QubesOS/qubes-doc into fedora-29-to-30

developer/debugging/automated-tests.md

@@ -152,6 +152,59 @@ Again, given the hypothetical `example.py` test:
             ):
 ~~~
 
+### Testing PyQt applications
+
+When testing (Py)QT application, it's useful to create separate QApplication object for each test.
+But QT framework does not allow to have multiple QApplication objects in the same process at the same time.
+This means it's critical to reliably cleanup previous instance before creating the new one.
+This turns out to be non-trivial task, especially if _any_ test uses event loop.
+Failure to perform proper cleanup in many cases results in SEGV.
+Below you can find steps for the proper cleanup:
+
+~~~python
+import asyncio
+import quamash
+import unittest
+import gc
+
+class SomeTestCase(unittest.TestCase):
+    def setUp(self):
+        [...]
+
+        # force "cleanlooks" style, the default one on Xfce (GtkStyle) use
+        # static variable internally and caches pointers to later destroyed
+        # objects (result: SEGV)
+        self.qtapp = QtGui.QApplication(["test", "-style", "cleanlooks"])
+
+        # construct event loop even if this particular test doesn't use it,
+        # otherwise events with qtapp references will be queued there anyway and the
+        # first test that actually use event loop will try to dereference (already
+        # destroyed) objects, resulting in SEGV
+        self.loop = quamash.QEventLoop(self.qtapp)
+    
+    def tearDown(self):
+        [...]
+        # process any pending events before destroying the object
+        self.qtapp.processEvents()
+
+        # queue destroying the QApplication object, do that for any other QT
+        # related objects here too
+        self.qtapp.deleteLater()
+
+        # process any pending events (other than just queued destroy), just in case
+        self.qtapp.processEvents()
+
+        # execute main loop, which will process all events, _including just queued destroy_
+        self.loop.run_until_complete(asyncio.sleep(0))
+
+        # at this point it QT objects are destroyed, cleanup all remaining references;
+        # del other QT object here too
+        self.loop.close()
+        del self.qtapp
+        del self.loop
+        gc.collect()
+~~~
+
 
 Installation Tests with openQA
 ------------------------------

developer/general/style-guide.md

@@ -68,7 +68,10 @@ Currently, all the icons on the Qubes-OS.org website are generated using [FontAw
 
 ## Logos
 
-The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website. All of these files are licensed GPLv2 and the source can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
+The following is a collection of various sizes and versions of the Qubes logo used both in the OS itself and on our website.
+The artwork is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
+The code is licensed under GNU GPLv2.
+GPLv2 and the source code can be [downloaded here](https://github.com/QubesOS/qubes-artwork).
 
 <div class="styleguide">
 {% for logo in site.data.styleguide.logos %}

doc.md

@@ -14,19 +14,17 @@ redirect_from:
 - /community/
 ---
 
-## User Documentation
+## Introduction
-
-### The Basics
 
  * [What is Qubes OS?](/intro/)
  * [Video Tours](/video-tours/)
  * [Screenshots](/screenshots/)
- * [Getting Started](/getting-started/)
  * [User FAQ](/faq/#users)
+ * [Reporting Bugs and Other Issues](/doc/reporting-bugs/)
  * [Help, Support, and Mailing Lists](/support/)
  * [How to Contribute](/doc/contributing/)
 
-### Security Information
+## Project Security
 
  * [Security Center](/security/)
  * [Security FAQ](/faq/#general--security)
@@ -34,184 +32,94 @@ redirect_from:
  * [Security Bulletins](/security/bulletins/)
  * [Canaries](/security/canaries/)
  * [Xen Security Advisory (XSA) Tracker](/security/xsa/)
- * [Why and How to Verify Signatures](/security/verifying-signatures/)
+ * [Verifying Signatures](/security/verifying-signatures/)
  * [Qubes PGP Keys](https://keys.qubes-os.org/keys/)
 
+
+## User Documentation
+
+Core documentation for Qubes users.
+
 ### Choosing Your Hardware
 
  * [System Requirements](/doc/system-requirements/)
  * [Certified Hardware](/doc/certified-hardware/)
  * [Hardware Compatibility List (HCL)](/hcl/)
 
-### Installing & Upgrading Qubes
+### Downloading, Installing, and Upgrading Qubes
 
- * [Qubes Downloads](/downloads/)
+ * [Downloads](/downloads/)
- * [Qubes Download Mirrors](/downloads/mirrors/)
  * [Installation Guide](/doc/installation-guide/)
  * [Upgrade Guides](/doc/upgrade/)
- * [Why and How to Verify Signatures](/security/verifying-signatures/)
- * [Security Considerations when Installing](/doc/install-security/)
- * [Try Qubes without installing: Qubes Live USB (alpha)](/doc/live-usb/)
  * [Supported Versions](/doc/supported-versions/)
  * [Version Scheme](/doc/version-scheme/)
- * [Custom Installation](/doc/custom-install/)
+ * [Testing New Releases and Updates](/doc/testing/)
- * [Testing new releases and updates](/doc/testing/)
 
 ### Common Tasks
 
+ * [Getting Started](/getting-started/)
  * [Copying and Pasting Text Between Domains](/doc/copy-paste/)
  * [Copying and Moving Files Between Domains](/doc/copying-files/)
  * [Copying from (and to) dom0](/doc/copy-from-dom0/)
  * [Installing and Updating Software in dom0](/doc/software-update-dom0/)
  * [Installing and Updating Software in VMs](/doc/software-update-vm/)
  * [Backup, Restoration, and Migration](/doc/backup-restore/)
- * [Using DisposableVMs](/doc/disposablevm/)
+ * [DisposableVMs](/doc/disposablevm/)
  * [Block (or Storage) Devices](/doc/block-devices/)
  * [USB Devices](/doc/usb-devices)
  * [PCI Devices](/doc/pci-devices/)
  * [Device Handling](/doc/device-handling/)
  * [Optical Discs](/doc/optical-discs/)
- * [Managing Application Shortcuts](/doc/managing-appvm-shortcuts/)
+ * [Application Shortcuts](/doc/managing-appvm-shortcuts/)
- * [Enabling Fullscreen Mode](/doc/full-screen-mode/)
+ * [Fullscreen Mode](/doc/full-screen-mode/)
- * [Tips and Tricks](/doc/tips-and-tricks/)
 
 ### Managing Operating Systems within Qubes
 
  * [TemplateVMs](/doc/templates/)
- * [Templates: Fedora](/doc/templates/fedora/)
+ * [Template: Fedora](/doc/templates/fedora/)
- * [Templates: Fedora Minimal](/doc/templates/fedora-minimal/)
+ * [Template: Fedora Minimal](/doc/templates/fedora-minimal/)
- * [Templates: Debian](/doc/templates/debian/)
+ * [Template: Debian](/doc/templates/debian/)
- * [Templates: Debian Minimal](/doc/templates/debian-minimal/)
+ * [Template: Debian Minimal](/doc/templates/debian-minimal/)
- * [Templates: Archlinux](/doc/templates/archlinux/)
- * [Templates: Ubuntu](/doc/templates/ubuntu/)
- * [Templates: Whonix](/doc/whonix/)
- * [Pentesting](/doc/pentesting/)
- * [Pentesting: BlackArch](/doc/pentesting/blackarch/)
- * [Pentesting: Kali](/doc/pentesting/kali/)
- * [Pentesting: PTF](/doc/pentesting/ptf/)
  * [Windows](/doc/windows/)
- * [Creating and Using HVM Domains](/doc/hvm/)
+ * [HVM Domains](/doc/hvm/)
- * [Tips for Using Linux in an HVM](/doc/linux-hvm-tips/)
- * [Creating a NetBSD VM](/doc/netbsd/)
- * [How to Reinstall a TemplateVM](/doc/reinstall-template/)
 
+### Security in Qubes
 
-### Security Guides
+ * [Qubes Firewall](/doc/firewall/)
-
- * [Qubes OS Project Security Information](/security/)
- * [Security Guidelines](/doc/security-guidelines/)
- * [Understanding Qubes Firewall](/doc/firewall/)
  * [Understanding and Preventing Data Leaks](/doc/data-leaks/)
- * [Installing Anti Evil Maid](/doc/anti-evil-maid/)
+ * [Anti Evil Maid](/doc/anti-evil-maid/)
- * [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/)
+ * [Split GPG](/doc/split-gpg/)
- * [Using GPG more securely in Qubes: Split GPG](/doc/split-gpg/)
+ * [U2F Proxy](/doc/u2f-proxy/)
- * [The Qubes U2F Proxy](/doc/u2f-proxy/)
- * [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/)
- * [[Unofficial] Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
- * [Configuring YubiKey for user authentication](/doc/yubi-key/)
- * [Security Considerations When Handling Devices](/doc/device-handling-security/)
- * [Note regarding password-less root access in VM](/doc/vm-sudo/)
 
-
+### Advanced Configuration
-### Privacy Guides
-
- * [Whonix for Privacy & Anonymity](/doc/whonix/)
- * [Running Tails in Qubes](/doc/tails/)
- * [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/)
- * [Martus](/doc/martus/)
- * [Signal](/doc/signal/)
- * [Reducing the fingerprint of the text-based web browser w3m](/doc/w3m/)
-
-
-### Configuration Guides
 
  * [Configuration Files](/doc/config-files/)
- * [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/)
  * [Storing AppVMs on Secondary Drives](/doc/secondary-storage/)
- * [Multibooting](/doc/multiboot/)
- * [Resize Disk Image](/doc/resize-disk-image/)
  * [RPC Policies](/doc/rpc-policy/)
- * [Changing your Time Zone](/doc/change-time-zone/)
- * [GUI Configuration and Troubleshooting](/doc/gui-configuration/)
- * [Installing ZFS in Qubes](/doc/zfs/)
- * [Mutt Guide](/doc/mutt/)
- * [Postfix Guide](/doc/postfix/)
- * [Fetchmail Guide](/doc/fetchmail/)
- * [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
- * [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
- * [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/network-bridge-support/)
  * [USB Qubes](/doc/usb-qubes/)
- * [Enabling TRIM for SSD disks](/doc/disk-trim/)
- * [Configuring a Network Printer](/doc/network-printer/)
- * [Using External Audio Devices](/doc/external-audio/)
- * [Rxvt Guide](/doc/rxvt/)
  * [Managing VM kernel](/doc/managing-vm-kernel/)
  * [Salt management stack](/doc/salt/)
- * [Adding SSD storage cache](https://groups.google.com/d/msgid/qubes-users/a08359c9-9eb0-4d1a-ad92-a8a9bc676ea6%40googlegroups.com)
- * [How to Make a Multimedia TemplateVM](/doc/multimedia/)
-
-
-### Customization Guides
-
  * [DisposableVM Customization](/doc/disposablevm-customization/)
- * [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization/)
- * [Customizing Windows 7 templates](/doc/windows-template-customization/)
- * [Using KDE in dom0](/doc/kde/)
- * [Installing i3 in dom0](/doc/i3/)
- * [Using awesome in dom0](/doc/awesome/)
- * [Language Localization](/doc/language-localization/)
- * [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
  * [How to make any file in a TemplateBasedVM persistent using bind-dirs](/doc/bind-dirs/)
- * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/)
-
-
-### Troubleshooting
-
- * [Home directory is out of disk space error](/doc/out-of-memory/)
- * [Newer hardware doesn't work](/doc/newer-hardware-troubleshooting/)
- * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
- * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
- * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
- * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/)
- * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/)
- * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/)
- * [Troubleshooting UEFI related problems](/doc/uefi-troubleshooting/)
- * [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/)
- * [How to remove VMs manually](/doc/remove-vm-manually/)
- * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
-
 
 ### Reference Pages
 
- * [Command-line tools](/doc/tools/)
+ * [Command-line Tools](/doc/tools/)
- * [Glossary of Qubes Terminology](/doc/glossary/)
+ * [Glossary](/doc/glossary/)
  * [Qubes Service Framework](/doc/qubes-service/)
  * [Command Execution in VMs (and Qubes RPC)](/doc/qrexec/)
- * [Deprecated documentation](https://github.com/QubesOS/qubesos.github.io#deprecated-documentation)
+ * [Deprecated Documentation](https://github.com/QubesOS/qubesos.github.io#deprecated-documentation)
 
 
-### Presentation Slides
-
- * [[PDF] LinuxCon 2014 -- Qubes OS R2 Tutorial](/attachment/wiki/slides/LinuxCon_2014_Qubes_Tutorial.pdf)
- * [[PDF] LinuxCon 2014 -- Qubes OS Keynote](/attachment/wiki/slides/LinuxCon_2014_Qubes_Keynote.pdf)
- * [[PDF] RMLL 2016 -- Improving client systems security with Qubes OS](/attachment/wiki/slides/RMLL_2016_Improving-client-systems-security.pdf)
- * [[PDF] Golem and Friends 2017 -- Towards Reasonably Secure Computing in the Decentralized World](/attachment/wiki/slides/Secure_Computing_in_Decentralized_World.pdf)
-
 ## Developer Documentation
 
-### The Basics
+Core documentation for Qubes developers and advanced users.
+
+### General
 
  * [Developer FAQ](/faq/#developers)
- * [Report a Security Issue](/security/)
- * [Report a Bug](/doc/reporting-bugs/)
- * [How to Contribute](/doc/contributing/)
  * [Package Contributions](/doc/package-contributions/)
- * [Testing new releases and updates](/doc/testing/)
- * [Source Code](/doc/source-code/)
- * [Qubes OS License](/doc/license/)
- * [Coding Guidelines](/doc/coding-style/)
  * [Documentation Guidelines](/doc/doc-guidelines/)
- * [Code Signing](/doc/code-signing/)
  * [Community-Developed Feature Tracker](/qubes-issues/)
  * [Google Summer of Code](/gsoc/)
  * [Google Season of Docs](/gsod/)
@@ -219,19 +127,12 @@ redirect_from:
  * [Style Guide](/doc/style-guide/)
  * [Usability & UX](/doc/usability-ux/)
 
-### Security Information
+### Code
 
- * [Security Center](/security/)
+ * [Source Code](/doc/source-code/)
- * [Security FAQ](/faq/#general--security)
+ * [Software License](/doc/license/)
- * [Security Pack](/security/pack/)
+ * [Coding Guidelines](/doc/coding-style/)
- * [Security Bulletins](/security/bulletins/)
+ * [Code Signing](/doc/code-signing/)
- * [Security Bulletin Checklist](/security/bulletins/checklist/)
- * [Security Bulletin Template](/security/bulletins/template/)
- * [Canaries](/security/canaries/)
- * [Canary Template](/security/canaries/template/)
- * [Xen Security Advisory (XSA) Tracker](/security/xsa/)
- * [Why and How to Verify Signatures](/security/verifying-signatures/)
- * [Qubes PGP Keys](http://keys.qubes-os.org/keys/)
 
 ### System
 
@@ -254,7 +155,6 @@ redirect_from:
  * [Inter-domain file copying](/doc/qfilecopy/) (deprecates [`qfileexchgd`](/doc/qfileexchgd/))
  * [Dynamic memory management in Qubes](/doc/qmemman/)
  * [Implementation of DisposableVMs](/doc/dvm-impl/)
- * [Article about DisposableVMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
  * [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
 
 ### Debugging
@@ -272,11 +172,7 @@ redirect_from:
  * [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
  * [Development Workflow](/doc/development-workflow/)
  * [Building Qubes OS ISO](/doc/qubes-iso-building/)
- * [Building Qubes Templates](https://github.com/QubesOS/qubes-template-configs)
+ * [Qubes Template Configuration Files](https://github.com/QubesOS/qubes-template-configs)
- * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
- * [Building the Archlinux Template](/doc/building-archlinux-template/)
- * [Building the Whonix Templates](/doc/building-whonix-template/)
- * [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion)
 
 ### Releases
 
@@ -284,3 +180,95 @@ redirect_from:
  * [Release schedules](/doc/releases/schedules/)
  * [Release checklist](/doc/releases/todo/)
 
+
+## External Documentation
+
+Unofficial, third-party documentation from the Qubes community and others.
+
+### Operating System Guides
+
+ * [Template: Archlinux](/doc/templates/archlinux/)
+ * [Template: Ubuntu](/doc/templates/ubuntu/)
+ * [Template: Whonix](/doc/whonix/)
+ * [Pentesting](/doc/pentesting/)
+ * [Pentesting: BlackArch](/doc/pentesting/blackarch/)
+ * [Pentesting: Kali](/doc/pentesting/kali/)
+ * [Pentesting: PTF](/doc/pentesting/ptf/)
+ * [Tips for Using Linux in an HVM](/doc/linux-hvm-tips/)
+ * [Creating a NetBSD VM](/doc/netbsd/)
+
+### Security Guides
+
+ * [Security Guidelines](/doc/security-guidelines/)
+ * [Using Multi-factor Authentication with Qubes](/doc/multifactor-authentication/)
+ * [How to Set Up a Split Bitcoin Wallet in Qubes](/doc/split-bitcoin/)
+ * [Split dm-crypt](https://github.com/rustybird/qubes-split-dm-crypt)
+ * [Configuring YubiKey for user authentication](/doc/yubi-key/)
+ * [Security Considerations When Handling Devices](/doc/device-handling-security/)
+ * [Note regarding password-less root access in VM](/doc/vm-sudo/)
+ * [Using OnlyKey with Qubes OS](https://docs.crp.to/qubes.html)
+
+### Privacy Guides
+
+ * [Whonix for Privacy & Anonymity](/doc/whonix/)
+ * [Running Tails in Qubes](/doc/tails/)
+ * [Anonymizing your MAC Address](/doc/anonymizing-your-mac-address/)
+ * [Martus](/doc/martus/)
+ * [Signal](/doc/signal/)
+ * [Reducing the fingerprint of the text-based web browser w3m](/doc/w3m/)
+
+### Configuration Guides
+
+ * [Qubes Tips and Tricks](/doc/tips-and-tricks/)
+ * [How to set up a ProxyVM as a VPN Gateway](/doc/vpn/)
+ * [Multibooting](/doc/multiboot/)
+ * [Resize Disk Image](/doc/resize-disk-image/)
+ * [Changing your Time Zone](/doc/change-time-zone/)
+ * [GUI Configuration and Troubleshooting](/doc/gui-configuration/)
+ * [Installing ZFS in Qubes](/doc/zfs/)
+ * [Mutt Guide](/doc/mutt/)
+ * [Postfix Guide](/doc/postfix/)
+ * [Fetchmail Guide](/doc/fetchmail/)
+ * [Creating Custom NetVMs and ProxyVMs](https://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html)
+ * [How to make proxy for individual tcp connection from networkless VM](https://groups.google.com/group/qubes-devel/msg/4ca950ab6d7cd11a)
+ * [Adding Bridge Support to the NetVM (EXPERIMENTAL)](/doc/network-bridge-support/)
+ * [Enabling TRIM for SSD disks](/doc/disk-trim/)
+ * [Configuring a Network Printer](/doc/network-printer/)
+ * [Using External Audio Devices](/doc/external-audio/)
+ * [Rxvt Guide](/doc/rxvt/)
+ * [Adding SSD storage cache](https://groups.google.com/d/msgid/qubes-users/a08359c9-9eb0-4d1a-ad92-a8a9bc676ea6%40googlegroups.com)
+ * [How to Make a Multimedia TemplateVM](/doc/multimedia/)
+
+### Customization Guides
+
+ * [Customizing Fedora minimal templates](/doc/fedora-minimal-template-customization/)
+ * [Customizing Windows 7 templates](/doc/windows-template-customization/)
+ * [Using KDE in dom0](/doc/kde/)
+ * [Installing i3 in dom0](/doc/i3/)
+ * [Using awesome in dom0](/doc/awesome/)
+ * [Language Localization](/doc/language-localization/)
+ * [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
+ * [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/)
+
+### Troubleshooting
+
+ * [Home directory is out of disk space error](/doc/out-of-memory/)
+ * [Newer hardware doesn't work](/doc/newer-hardware-troubleshooting/)
+ * [Installing on system with new AMD GPU (missing firmware problem)](https://groups.google.com/group/qubes-devel/browse_thread/thread/e27a57b0eda62f76)
+ * [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
+ * [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
+ * [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/)
+ * [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/)
+ * [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/)
+ * [Troubleshooting UEFI related problems](/doc/uefi-troubleshooting/)
+ * [Fixing wireless on suspend & resume](/doc/wireless-troubleshooting/)
+ * [How to remove VMs manually](/doc/remove-vm-manually/)
+ * [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
+
+### Building Guides
+
+ * [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
+ * [Building the Archlinux Template](/doc/building-archlinux-template/)
+ * [Building the Whonix Templates](/doc/building-whonix-template/)
+ * [How to compile kernels for dom0](https://groups.google.com/d/topic/qubes-users/yBeUJPwKwHM/discussion)
+