mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-05-02 06:46:11 -04:00
Move all developer documentation to main index
QubesOS/qubes-issues#2070
This commit is contained in:
Andrew David Wong
parent
254f5e71a0
commit
aadb35d62f
39 changed files with 46 additions and 3 deletions
139
basics_dev/code-signing.md
Normal file
139
basics_dev/code-signing.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Code Signing
|
||||
permalink: /doc/code-signing/
|
||||
---
|
||||
|
||||
Code Signing
|
||||
============
|
||||
|
||||
All contributions to the Qubes OS [source code] must be cryptographically signed
|
||||
by the author's PGP key.
|
||||
|
||||
|
||||
Generating a Key
|
||||
----------------
|
||||
|
||||
(Note: If you already have a PGP key, you may skip this step.)
|
||||
|
||||
Alex Cabal has written an excellent [guide] on creating a PGP keypair.
|
||||
Below, we reproduce just the minimum steps in generating a keypair using GnuPG.
|
||||
Please read Cabal's full guide for further important details.
|
||||
|
||||
~~~
|
||||
$ gpg --gen-key
|
||||
gpg (GnuPG) 1.4.11; Copyright (C) 2010 Free Software Foundation, Inc.
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
|
||||
Please select what kind of key you want:
|
||||
(1) RSA and RSA (default)
|
||||
(2) DSA and Elgamal
|
||||
(3) DSA (sign only)
|
||||
(4) RSA (sign only)
|
||||
Your selection? 1
|
||||
|
||||
RSA keys may be between 1024 and 4096 bits long.
|
||||
What keysize do you want? (2048) 4096
|
||||
|
||||
Requested keysize is 4096 bits
|
||||
Please specify how long the key should be valid.
|
||||
0 = key does not expire
|
||||
<n> = key expires in n days
|
||||
<n>w = key expires in n weeks
|
||||
<n>m = key expires in n months
|
||||
<n>y = key expires in n years
|
||||
Key is valid for? (0) 0
|
||||
|
||||
Key does not expire at all
|
||||
Is this correct? (y/N) y
|
||||
|
||||
|
||||
You need a user ID to identify your key; the software constructs the user ID
|
||||
from the Real Name, Comment and E-mail Address in this form:
|
||||
"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
|
||||
|
||||
Real name: Bilbo Baggins
|
||||
|
||||
E-mail address: bilbo@shire.org
|
||||
|
||||
Comment:
|
||||
You selected this USER-ID:
|
||||
"Bilbo Baggins <bilbo@shire.org>"
|
||||
|
||||
Change (N)ame, (C)omment, (E)-mail or (O)kay/(Q)uit? O
|
||||
|
||||
You need a Passphrase to protect your secret key.
|
||||
|
||||
<type your passphrase>
|
||||
|
||||
gpg: key 488BA441 marked as ultimately trusted
|
||||
public and secret key created and signed.
|
||||
|
||||
gpg: checking the trustdb
|
||||
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
|
||||
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
|
||||
pub 4096R/488BA441 2013-03-13
|
||||
Key fingerprint = B878 1FB6 B187 B94C 3E52 2AFA EB1D B79A 488B A441
|
||||
uid Bilbo Baggins <bilbo@shire.org>
|
||||
sub 4096R/69B0EA85 2013-03-13
|
||||
~~~
|
||||
|
||||
|
||||
Using PGP with Git
|
||||
------------------
|
||||
|
||||
If you're submitting a patch via GitHub (or a similar Git server), please sign
|
||||
your Git commits.
|
||||
|
||||
1. Set up Git to use your key:
|
||||
|
||||
~~~
|
||||
git config --global user.signingkey <KEYID>
|
||||
~~~
|
||||
|
||||
2. Set up Git to sign your commits with your key:
|
||||
|
||||
~~~
|
||||
git config --global commit.gpgsign true
|
||||
~~~
|
||||
|
||||
Alternatively, manually specify when a commit is to be signed:
|
||||
|
||||
~~~
|
||||
commit -S
|
||||
~~~
|
||||
|
||||
3. (Optional) Create signed tags:
|
||||
|
||||
~~~
|
||||
git tag -s <tag_name> -m "<tag_message>"
|
||||
~~~
|
||||
|
||||
You can also create an alias to make this easier:
|
||||
|
||||
~~~
|
||||
stag = "!id=`git rev-parse --verify HEAD`; git tag -s tag_for_${id:0:8} -m \"Tag for commit $id\""
|
||||
~~~
|
||||
|
||||
You may also find it convenient to have an alias for verifying the tag on the
|
||||
latest commit:
|
||||
|
||||
~~~
|
||||
vtag = !git tag -v `git describe`
|
||||
~~~
|
||||
|
||||
|
||||
Using PGP with Email
|
||||
--------------------
|
||||
|
||||
If you're submitting a patch via email (to the developer [mailing list]), simply
|
||||
sign your email with your PGP key. (One good way to do this is with a program
|
||||
like [Enigmail].)
|
||||
|
||||
|
||||
[guide]: https://alexcabal.com/creating-the-perfect-gpg-keypair/
|
||||
[source code]: /doc/source-code/
|
||||
[mailing list]: /doc/mailing-lists/
|
||||
[Enigmail]: https://www.enigmail.net/
|
||||
|
||||
171
basics_dev/coding-style.md
Normal file
171
basics_dev/coding-style.md
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Coding Style
|
||||
permalink: /doc/coding-style/
|
||||
redirect_from:
|
||||
- /en/doc/coding-style/
|
||||
- /doc/CodingStyle/
|
||||
- /wiki/CodingStyle/
|
||||
- /trac/wiki/CodingStyle/
|
||||
---
|
||||
|
||||
Coding Guidelines for Qubes Developers
|
||||
======================================
|
||||
|
||||
Rationale
|
||||
---------
|
||||
|
||||
Maintaining proper coding style is very important for any larger software project, such as Qubes. Here's why:
|
||||
|
||||
- It eases maintenance, such as adding new functionality or generalization later,
|
||||
- It allows others (as well as the original author after some time!) to easily understand fragments of code, what they were supposed to do, and so makes it easier to later extend them with newer functionality or bug fixes,
|
||||
- It allows others to easily review the code and catch various bugs,
|
||||
- It provides for an aesthetically pleasing experience when one reads the code...
|
||||
|
||||
Often, developers, usually smart developers, neglect the value of proper coding style, thinking that it's most important how their code works, and expecting that if it solves some problem using a nice and neat trick, then it's all that is really required. Such thinking shows, however, immaturity and is a signal that the developer, however bright and smart, might not be a good fit for any larger project. Writing a clever exploit, that is to be used at one Black Hat show is one thing, while writing a useful software that is to be used and maintained for years, is quite a different story. If you want to show off what a smart programmer you are, then you should become a researcher and write exploits. If, on the other hand, you want to be part of a team that makes real, useful software, you should ensure your coding style is impeccable. We often, at Qubes project, often took shortcuts, and often wrote nasty code, and this always back fired at us, sometime months, sometime years later, the net result being we had to spend time fixing code, rather than implementing new functionality.
|
||||
|
||||
And here's a [link to the real case](https://groups.google.com/forum/#!msg/qubes-devel/XgTo6L8-5XA/JLOadvBqnqMJ) (one Qubes Security Bulletin) demonstrating how the above described problem lead to a real security bug. Never assume you're smart enough that you can disregard clean and rigorous coding!
|
||||
|
||||
General typographic conventions
|
||||
-------------------------------
|
||||
|
||||
- **Use space-expanded tabs that equal 4 spaces.** Yes, we know, there are many arguments for using "real" tabs, instead of space-expanded tabs, but we need to pick one convention to make the project consistent. One argument for using space-expanded tabs is that this way the programmer is in control of how the code will look like, despite how other users have configured their editors to visualize the tabs (of course, we assume any sane person uses a fixed-width font for viewing the source code). Anyway, if this makes you feel better, assume this is just an arbitrary choice.
|
||||
|
||||
- **Maintain max. line length of 80 characters**. Even though today's monitors often are very wide and it's often not a problem to have 120 characters displayed in an editor, still maintaining shorter line lengths improves readability. It also allows to have two parallel windows open, side by side, each with different parts of the source code.
|
||||
|
||||
- Class, functions, variables, and arguments naming convention for any OS other than Windows:
|
||||
- `ClassName`
|
||||
- `some_variable`, `some_function`, `some_argument`
|
||||
|
||||
- Class, functions, variables, and arguments naming convention for **Windows OS** -- exceptionally to preserve Windows conventions please use the following:
|
||||
- `ClassName`, `FunctionName`
|
||||
- `pszArgumentOne`, `hPipe` -- use Hungarian notation for argument and variables
|
||||
|
||||
- Horizontal spacing -- maintain at least decent amount of horizontal spacing, such as e.g. add obligatory space after `if` or before `{` in C, and similar in other languages. Whether to also use spaces within expressions, such as (x\*2+5) vs. (x \* 2 + 5) is left to the developer's judgment. Do not put spaces immediately after and before the brackets in expressions, so avoid constructs like this: `if ( condition )` and use `if (condition)` instead.
|
||||
|
||||
- **Use single new lines** ('\\n' aka LF) in any non-Windows source code. On Windows, exceptionally, use the CRLF line endings -- this will allow the source code to be easily view-able in various Windows-based programs.
|
||||
|
||||
- **Use descriptive names for variables and functions**! Really, these days, when most editors have auto-completion feature, there is no excuse for using short variable names.
|
||||
|
||||
- Comments should be indent together with the code, e.g. like this:
|
||||
|
||||
~~~
|
||||
for (...) {
|
||||
// The following code finds PGP private key matching the given public key in O(1)
|
||||
while (key_found) {
|
||||
(...)
|
||||
}
|
||||
}
|
||||
~~~
|
||||
|
||||
File naming conventions
|
||||
-----------------------
|
||||
|
||||
- All file names written with small letters, use dash to separate words, rather than underscores, e.g. `qubes-dom0-update`. Never use spaces!
|
||||
|
||||
**File naming in Linux/Unix-like systems:**
|
||||
|
||||
- User commands that operate on particular VMs (also those accessible in VMs): `/usr/bin/qvm-*`
|
||||
- User commands that apply to the whole system (Dom0 only): `/usr/bin/qubes-*`
|
||||
- Auxiliary executables and scripts in `/usr/libexec/qubes/` (Note: previously we used `/usr/lib/qubes` but decided to change that)
|
||||
- Helper, non-executable files in `/usr/share/qubes/`
|
||||
- Various config files in `/etc/qubes`
|
||||
- Qubes RPC services in `/etc/qubes-rpc`. Qubes RPC Policy definitions (only in Dom0) in `/etc/qubes-rpc/policy/`
|
||||
- All VM-related configs, images, and other files in `/var/lib/qubes/`
|
||||
- System-wide temporary files which reflect the current state of system in `/var/run/qubes`
|
||||
- Logs: either log to the system-wide messages, or to `/var/log/qubes/`
|
||||
|
||||
**File naming in Windows systems:**
|
||||
|
||||
- All base qubes-related files in `C:\Program Files\Invisible Things Lab\Qubes\` (Exceptionally spaces are allowed here to adhere to Windows naming conventions)
|
||||
- Other, 3rd party files, not Qubes-specific, such as e.g. Xen PV drivers might be in different vendor subdirs, e.g. `C:\Program Files\Xen PV Drivers`
|
||||
|
||||
General programming style guidelines
|
||||
------------------------------------
|
||||
|
||||
- Do not try to impress with your coding kung-fu, do not use tricks to save 2 lines of code, always prefer readability over trickiness!
|
||||
- Make sure your code compiles and builds without warnings.
|
||||
- Always think first about interfaces (e.g. function arguments, or class methods) and data structures before you start writing the actual code.
|
||||
- Use comments to explain non-trivial code fragments, or expected behavior of more complex functions, if it is not clear from their name.
|
||||
- Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this:
|
||||
|
||||
~~~
|
||||
// Return window id
|
||||
int get_window_id (...) {
|
||||
(...)
|
||||
return id;
|
||||
}
|
||||
~~~
|
||||
|
||||
- Do **not** use comments to disable code fragments. In a production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use \#if or \#ifdef to disable it, e.g.:
|
||||
|
||||
~~~
|
||||
#if 0
|
||||
(...) // Some unused code here
|
||||
#endif
|
||||
~~~
|
||||
|
||||
... and preferably use some descriptive macro instead of just `0`, e.g.:
|
||||
|
||||
~~~
|
||||
#if USE_OLD_WINDOW_TRAVERSING
|
||||
(...) // Some unused code here
|
||||
#endif
|
||||
~~~
|
||||
|
||||
Not sure how to do similar thing in Python... Anyone?
|
||||
|
||||
> But generally, there is little excuse to keep old, unused code fragments in the code. One should really use the functionality provided by the source code management system, such as git, instead. E.g. create a special branch for storing the old, unused code -- this way you will always be able to merge this code into upstream in the future.
|
||||
|
||||
- Do not hardcode values in the code! The only three numbers that are an exception here and for which it is acceptable to hardcode them are: `0`, `1` and `-1`, and frankly the last two are still controversial...
|
||||
|
||||
Source Code management (Git) guidelines
|
||||
---------------------------------------
|
||||
|
||||
- Use git to maintain all code for Qubes project.
|
||||
|
||||
- Before you start using git, make sure you understand that git is a decentralized Source Code Management system, and that it doesn't behave like traditional, centralized source code management systems, such as SVN. Here's a good [introductory book on git](http://git-scm.com/book). Read it.
|
||||
|
||||
- Qubes code is divided into many git repositories. There are several reasons for that:
|
||||
- This creates natural boundaries between different code blocks, enforcing proper interfaces, and easing independent development to be conducted on various code parts at the same time, without the fear of running into conflicts.
|
||||
- By maintaining relatively small git repositories, it is easy for new developers to understand the code and contribute new patches, without the need to understand all the other code.
|
||||
- Code repositories represent also licensing boundaries. So, e.g. because `core-agent-linux` and `core-agent-windows` are maintained in two different repositories, it is possible to have the latter under a proprietary, non-GPL license, while keeping the former fully open source.
|
||||
- We have drastically changes the layout and naming of the code repositories shortly after Qubes OS R2 Beta 2 release. For details on the current code layout, please read [this article](http://theinvisiblethings.blogspot.com/2013/03/introducing-qubes-odyssey-framework.html).
|
||||
|
||||
Security coding guidelines
|
||||
--------------------------
|
||||
|
||||
- As a general rule: **untrusted input** is our \#1 enemy!
|
||||
- Any input that comes from untrusted, or less trusted, or just differently-trusted, entity should always be considered as malicious and should always be sanitized and verified. So, if your software runs in Dom0 and processes some input from any of the VMs, this input should be considered to be malicious. Even if your software runs in a VM, and processes input from some other VM, you should also assume that the input is malicious and verify it.
|
||||
- Use `untrusted_` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.:
|
||||
|
||||
~~~
|
||||
read_struct(untrusted_conf);
|
||||
/* sanitize start */
|
||||
if (untrusted_conf.width > MAX_WINDOW_WIDTH)
|
||||
untrusted_conf.width = MAX_WINDOW_WIDTH;
|
||||
if (untrusted_conf.height > MAX_WINDOW_HEIGHT)
|
||||
untrusted_conf.height = MAX_WINDOW_HEIGHT;
|
||||
width = untrusted_conf.width;
|
||||
height = untrusted_conf.height;
|
||||
~~~
|
||||
|
||||
- Use another variables, without the `untrusted_` prefix to hold the sanitized values, as shown above.
|
||||
|
||||
Python-specific guidelines
|
||||
--------------------------
|
||||
|
||||
- Please follow the guidelines [here](http://www.python.org/dev/peps/pep-0008/), unless they were in conflict with what is written on this page.
|
||||
|
||||
C and C++ specific guidelines
|
||||
-----------------------------
|
||||
|
||||
- Do not place code in `*.h` files.
|
||||
- Use `const` whenever possible, e.g. in function arguments passed via pointers.
|
||||
- Do not mix procedural and objective code together -- if you write in C++, use classes and objects.
|
||||
- Think about classes hierarchy, before start implementing specific methods.
|
||||
|
||||
Bash-specific guidelines
|
||||
------------------------
|
||||
|
||||
- Avoid writing scripts in bash whenever possible. Use python instead. Bash-scripts are Unix-specific and will not work under Windows VMs, or in Windows admin domain, or Windows gui domain.
|
||||
34
basics_dev/contributing.md
Normal file
34
basics_dev/contributing.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Contributing
|
||||
permalink: /doc/contributing/
|
||||
redirect_from:
|
||||
- /en/doc/contributing/
|
||||
- /doc/ContributingHowto/
|
||||
- /wiki/ContributingHowto/
|
||||
---
|
||||
|
||||
How can I contribute to the Qubes Project?
|
||||
==========================================
|
||||
|
||||
Ok, so you think Qubes Project is cool and you would like to contribute? You are very welcome!
|
||||
|
||||
First you should decide what you are interested in (and good in). The Qubes project would welcome contributions in various areas:
|
||||
|
||||
- Testing and [bug reporting](/doc/reporting-bugs/)
|
||||
- Code audit (e.g. gui-daemon)
|
||||
- New features
|
||||
- Artwork (plymouth themes, KDM themes, installer themes, wallpapers, etc)
|
||||
- [Documentation](/doc/doc-guidelines)
|
||||
|
||||
Perhaps the best starting point is to have a look at the [issues](https://github.com/QubesOS/qubes-issues/issues) to see what are the most urgent tasks to do.
|
||||
|
||||
Before you engage in some longer activity, e.g. implementing a new feature, it's always good to contact us first (preferably via the [qubes-devel](/doc/mailing-lists/) list), to avoid a situation when two or more independent people would work on the same feature at the same time, doubling each other's work. When you contact us and devote to a particular task, we will create a ticket for this task with info who is working on this feature and what is the expected date of some early code to be posted.
|
||||
|
||||
When you are ready to start some work, read how to [access Qubes sources and send patches](/doc/source-code/).
|
||||
|
||||
You can also contribute in other areas than coding and testing, e.g. by providing mirrors for Qubes rpm repositories, providing feedback about what features you would like to have in Qubes, or perhaps even preparing some cool You Tube videos that would demonstrate some Qubes' features. You are always encouraged to discuss your ideas on qubes-devel.
|
||||
|
||||
You should be aware, however, that we will not blindly accept all the contributions! We will accept only the quality ones. Open source doesn't mean lack of quality control! If we reject your patch, please do not get discouraged, try fixing it so that it adheres to the required standards. We will only reject contributions in the good faith, to make Qubes a better OS.
|
||||
|
||||
Thanks, [The Qubes Project team](/team).
|
||||
29
basics_dev/devel-books.md
Normal file
29
basics_dev/devel-books.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Developer Books
|
||||
permalink: /doc/devel-books/
|
||||
redirect_from:
|
||||
- /en/doc/devel-books/
|
||||
- /doc/DevelBooks/
|
||||
- /wiki/DevelBooks/
|
||||
---
|
||||
|
||||
Below is a list of various books that might be useful in learning some basics needed for Qubes development.
|
||||
|
||||
- A must-read about Xen internals:
|
||||
- [http://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X](http://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)
|
||||
|
||||
- Some good books about Linux kernel:
|
||||
- [http://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672327201](http://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672327201)
|
||||
- [http://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903](http://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)
|
||||
|
||||
- Solid intro into Trusted Computing by David Grawrock (original Intel architect for TXT):
|
||||
- [http://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082](http://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)
|
||||
|
||||
- Good book about GIT:
|
||||
- [http://progit.org/book/](http://progit.org/book/)
|
||||
|
||||
- Useful books about Python:
|
||||
- [http://www.qtrac.eu/py3book.html](http://www.qtrac.eu/py3book.html) (Note that Qubes management tools are written in Python 2.6, but this book is still a very good choice)
|
||||
- [http://www.qtrac.eu/pyqtbook.html](http://www.qtrac.eu/pyqtbook.html)
|
||||
|
||||
47
basics_dev/devel-faq.md
Normal file
47
basics_dev/devel-faq.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Developers' FAQ
|
||||
permalink: /doc/devel-faq/
|
||||
redirect_from:
|
||||
- /en/doc/devel-faq/
|
||||
- /doc/DevelFaq/
|
||||
- /wiki/DevelFaq/
|
||||
---
|
||||
|
||||
Qubes Developers' FAQ
|
||||
=====================
|
||||
|
||||
Q: Why does dom0 need to be 64-bit?
|
||||
-----------------------------------
|
||||
|
||||
Since 2013 [Xen has not supported 32-bit x86 architecture](http://wiki.xenproject.org/wiki/Xen_Project_Release_Features) and Intel VT-d, which Qubes uses to isolate devices and drivers, is available on Intel 64-bit processors only.
|
||||
|
||||
In addition, often it is more difficult to exploit a bug on the x64 Linux than it is on x86 Linux (e.g. ASLR is sometimes harder to get around). While we designed Qubes with the emphasis on limiting any potential attack vectors in the first place, still we realize that some of the code running in Dom0, e.g. our GUI daemon or xen-store daemon, even though it is very simple code, might contain some bugs. Plus currently we haven't implemented a separate storage domain, so also the disk backends are in Dom0 and are "reachable" from the VMs, which adds up to the potential attack surface. So, having faced a choice between 32-bit and 64-bit OS for Dom0, it was almost a no-brainer, as the 64-bit option provides some (little perhaps, but still) more protection against some classes of attacks, and at the same time does not have any disadvantages (except that it requires a 64-bit processor, but all systems on which it makes sense to run Qubes, e.g. that have at least 3-4GB memory, they do have 64-bit CPUs anyway).
|
||||
|
||||
Q: Why do you use KDE in Dom0? What is the roadmap for Gnome support?
|
||||
---------------------------------------------------------------------
|
||||
|
||||
There are a few things that are KDE-specific, but generally it should not be a big problem to also add Gnome support to Qubes (in Dom0 of course). Those KDE-specific things are:
|
||||
|
||||
- Qubes requires KDM (KDE Login Manager), rather than GDM, for the very simple reason that GDM doesn't obey standards and start `/usr/bin/Xorg` instead of `/usr/bin/X`. This is important for Qubes, because we need to load a special "X wrapper" (to make it possible to use Linux usermode shared memory to access Xen shared memory pages in our App Viewers -- see the sources [here](https://github.com/QubesOS/qubes-gui-daemon/tree/master/shmoverride)). So, Qubes makes the `/usr/bin/X` to be a symlink to the Qubes X Wrapper, which, in turn, executes the `/usr/bin/Xorg`. This works well with KDM (and would probably also work with other X login managers), but not with GDM. If somebody succeeded in makeing GDM to execute `/usr/bin/X` instead of `/usr/bin/Xorg`, we would love to hear about it!
|
||||
|
||||
- We maintain a special [repository](/doc/kde-dom0/) for building packages specifically for Qubes Dom0.
|
||||
|
||||
- We've patched the KDE's Window Manager (specifically [one of the decoration plugins](https://github.com/QubesOS/qubes-desktop-linux-kde/tree/master/plastik-for-qubes)) to draw window decorations in the color of the specific AppVM's label.
|
||||
|
||||
If you're interested in porting GNOME for Qubes Dom0 use, let us know -- we will most likely welcome patches in this area.
|
||||
|
||||
Q: What is the recommended build environment?
|
||||
---------------------------------------------
|
||||
|
||||
Any rpm-based, 64-bit. Preferred Fedora.
|
||||
|
||||
Q: How to build Qubes from sources?
|
||||
-----------------------------------
|
||||
|
||||
See [the instruction](/doc/qubes-builder/)
|
||||
|
||||
Q: How do I submit a patch?
|
||||
---------------------------
|
||||
|
||||
See [Qubes Source Code Repositories](/doc/source-code/).
|
||||
168
basics_dev/doc-guidelines.md
Normal file
168
basics_dev/doc-guidelines.md
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Documentation Guidelines
|
||||
permalink: /doc/doc-guidelines/
|
||||
redirect_from:
|
||||
- /en/doc/doc-guidelines/
|
||||
- /wiki/DocStyle/
|
||||
- /doc/DocStyle/
|
||||
---
|
||||
|
||||
Documentation Guidelines
|
||||
========================
|
||||
|
||||
All Qubes OS documentation pages are stored as plain text files in the
|
||||
dedicated [qubes-doc] repository. By cloning and regularly pulling from
|
||||
this repo, users can maintain their own up-to-date offline copy of all Qubes
|
||||
documentation rather than relying solely on the Web.
|
||||
|
||||
The documentation is a community effort in which volunteers work hard trying to
|
||||
keep everything accurate and comprehensive. If you notice a problem with the
|
||||
documentation or some way it can be improved, please [report] it! Better
|
||||
yet, you can [edit the documentation][contribute] yourself, both to add new
|
||||
content and to edit existing content.
|
||||
|
||||
|
||||
How to Report Issues
|
||||
--------------------
|
||||
|
||||
To report an issue, please create an issue in [qubes-issues], but before you do,
|
||||
please make sure your issue does **not** already exist. Documentation-related
|
||||
issues will be assigned the `doc` label. Issues which have been created in
|
||||
[qubes-issues] are significantly more likely to be addressed than those sent in
|
||||
emails to the mailing lists or to individuals.
|
||||
|
||||
|
||||
How to Contribute
|
||||
-----------------
|
||||
|
||||
Editing the documentation is easy, so if you spot any errors, please help us
|
||||
fix them! (As mentioned above, the documentation maintainers are just volunteers
|
||||
who have day jobs of their own, so we rely heavily on the community to improve
|
||||
the documentation.) Since Qubes is a security-oriented project, every
|
||||
documentation change will be reviewed before it's published to the web. This
|
||||
allows us to maintain quality control and protect our users.
|
||||
|
||||
As mentioned above, we keep all the documentation in a dedicated [Git
|
||||
repository][qubes-doc] hosted on [GitHub]. Thanks to GitHub interface, you can
|
||||
edit the documentation even if you don't know Git at all! The only thing you
|
||||
need is a GitHub account, which is free.
|
||||
|
||||
(Note: If you're already familiar with GitHub or wish to work from the command
|
||||
line, you can skip the rest of this section. All you need to do to contribute is
|
||||
to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then
|
||||
[submit a pull request][gh-pull].)
|
||||
|
||||
Ok, let's start. Every documentation page has an "Edit this page" button. It may
|
||||
be on the right side (in the desktop layout):
|
||||
|
||||
|
||||
|
||||
Or at the bottom (in the mobile layout):
|
||||
|
||||
|
||||
|
||||
When you click on it, you'll be prompted for your GitHub username and password
|
||||
(if you aren't already logged in). You can also create an account from here.
|
||||
|
||||
|
||||
|
||||
If this is your first contribution to the documentation, you need to "fork" the
|
||||
repository (make your own copy). It's easy --- just click the big green button
|
||||
on the next page. This step is only needed the first time you make a
|
||||
contribution.
|
||||
|
||||
|
||||
|
||||
Now you can make your modifications. You can also preview the changes to see how
|
||||
they'll be formatted by clicking the "Preview changes" tab.
|
||||
|
||||
|
||||
|
||||
Once you're finish, describe your changes at the bottom and click "Propose file
|
||||
change".
|
||||
|
||||
|
||||
|
||||
After that, you'll see exactly what modifications you've made. At this stage,
|
||||
those changes are still in your own copy of the documentation ("fork"). If
|
||||
everything looks good, send those changes to us by pressing the "Create pull
|
||||
request" button.
|
||||
|
||||
|
||||
|
||||
You will be able to adjust the pull request message and title there. In most
|
||||
cases, the defaults are ok, so you can just confirm by pressing the "Create pull
|
||||
request" button again.
|
||||
|
||||
|
||||
|
||||
That's all! We will review your changes. If everything looks good, we'll pull
|
||||
them into the official documentation. Otherwise, we may have some questions for
|
||||
you, which we'll post in a comment on your pull request. (GitHub will
|
||||
automatically notify you if we do.) If, for some reason, we can't accept your
|
||||
pull request, we'll post a comment explaining why we can't.
|
||||
|
||||
|
||||
|
||||
|
||||
Style Guidelines
|
||||
----------------
|
||||
|
||||
* Familiarize yourself with the terms defined in the [glossary]. Use these
|
||||
terms consistently and accurately throughout your writing.
|
||||
|
||||
|
||||
Markdown Conventions
|
||||
--------------------
|
||||
|
||||
All the documentation is written in Markdown for maximum accessibility. When
|
||||
making contributions, please try to observe the following style conventions:
|
||||
|
||||
* Use spaces instead of tabs.
|
||||
* Hard wrap Markdown lines at 80 characters.
|
||||
* If appropriate, make numerals in numbered lists match between Markdown
|
||||
source and HTML output.
|
||||
* Rationale: In the event that a user is required to read the Markdown source
|
||||
directly, this will make it easier to follow, e.g., numbered steps in a set
|
||||
of instructions.
|
||||
* Use hanging indentations
|
||||
where appropriate.
|
||||
* Use underline headings (`=====` and `-----`) if possible. If this is not
|
||||
possible, use Atx-style headings on both the left and right sides
|
||||
(`### H3 ###`).
|
||||
* Use `[reference-style][ref]` links.
|
||||
|
||||
`[ref]: https://daringfireball.net/projects/markdown/syntax#link`
|
||||
|
||||
([This][md] is a great source for learning about Markdown.)
|
||||
|
||||
|
||||
Git Conventions
|
||||
---------------
|
||||
|
||||
Please attempt to follow these conventions when writing your Git commit
|
||||
messages:
|
||||
|
||||
* Separate the subject line from the body with a blank line.
|
||||
* Limit the subject line to approximately 50 characters.
|
||||
* Capitalize the subject line.
|
||||
* Do not end the subject line with a period.
|
||||
* Use the imperative mood in the subject line.
|
||||
* Wrap the body at 72 characters.
|
||||
* Use the body to explain *what* and *why* rather than *how*.
|
||||
|
||||
For details, examples, and the rationale behind each of these conventions,
|
||||
please see [this blog post][git-commit], which is the source of this list.
|
||||
|
||||
|
||||
[qubes-doc]: https://github.com/QubesOS/qubes-doc
|
||||
[glossary]: /doc/glossary/
|
||||
[report]: #how-to-report-issues
|
||||
[contribute]: #how-to-contribute
|
||||
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
|
||||
[gh-fork]: https://guides.github.com/activities/forking/
|
||||
[gh-pull]: https://help.github.com/articles/using-pull-requests/
|
||||
[GitHub]: https://github.com/
|
||||
[md]: https://daringfireball.net/projects/markdown/
|
||||
[git-commit]: http://chris.beams.io/posts/git-commit/
|
||||
21
basics_dev/license.md
Normal file
21
basics_dev/license.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
layout: doc
|
||||
title: License
|
||||
permalink: /doc/license/
|
||||
redirect_from:
|
||||
- /en/doc/license/
|
||||
- /doc/QubesLicensing/
|
||||
- /wiki/QubesLicensing/
|
||||
---
|
||||
|
||||
Qubes OS License
|
||||
================
|
||||
|
||||
Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2.
|
||||
|
||||
The full text of the GPL v2 license can be found [here](http://www.gnu.org/licenses/gpl-2.0.html).
|
||||
|
||||
Note on rights to double-licensing of the Qubes code
|
||||
----------------------------------------------------
|
||||
|
||||
Invisible Things Lab (ITL), who has funded and run the Qubes project since the beginning, and who has contributed majority of Qubes-specific code (specifically: `core-*`, `gui-*`, and `qubes-*` repositories) would like to have a right to redistribute parts of this code under proprietary licenses. This is especially important for Qubes R3 and later, where the new architecture allows the creation of many editions of Qubes, using different hypervisors, some of which might not be open source. That's why we ask every developer who contributes code to Qubes project to grant ITL permission to reuse the code under a different license, and to express this consent by including the [standard signed-off line](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=HEAD#n358) in the commit.
|
||||
81
basics_dev/reporting-bugs.md
Normal file
81
basics_dev/reporting-bugs.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Reporting Bugs
|
||||
permalink: /doc/reporting-bugs/
|
||||
redirect_from:
|
||||
- /en/doc/reporting-bugs/
|
||||
- /doc/BugReportingGuide/
|
||||
- /wiki/BugReportingGuide/
|
||||
---
|
||||
|
||||
Bug Reporting Guide
|
||||
===================
|
||||
|
||||
One of the most important contribution task is reporting the bugs you have found.
|
||||
|
||||
Asking a Question
|
||||
-----------------
|
||||
|
||||
Before you ask, do some searching and reading. Check [the
|
||||
docs](https://www.qubes-os.org/doc/), Google, GitHub, and StackOverflow. If
|
||||
your question is something that has been answered many times before, the
|
||||
project maintainers might be tired of repeating themselves.
|
||||
|
||||
Whenever possible, ask your question on the Qubes mailing list which is
|
||||
located [here](https://groups.google.com/forum/#!forum/qubes-users). This
|
||||
allows anyone to answer and makes the answer available for the next person
|
||||
with the same question.
|
||||
|
||||
Submitting a Bug Report (or "Issue")
|
||||
------------------------------------
|
||||
|
||||
On GitHub, "Bug Reports" are called "Issues."
|
||||
|
||||
Issues can be submitted to the Qubes project located at
|
||||
[https://github.com/QubesOS/qubes-issues](https://github.com/QubesOS/qubes-issues).
|
||||
|
||||
### Has This Been Asked Before?
|
||||
|
||||
Before you submit a bug report, you should search existing issues. Be sure
|
||||
to check both currently open issues, as well as issues that are already
|
||||
closed. If you find an issue that seems to be similar to yours, read
|
||||
through it.
|
||||
|
||||
If this issue is the same as yours, you can comment with additional
|
||||
information to help the maintainer debug it. Adding a comment will
|
||||
subscribe you to email notifications, which can be helpful in getting
|
||||
important updates regarding the issue. If you don't have anything to add
|
||||
but still want to receive email updates, you can click the "watch" button
|
||||
at the bottom of the comments.
|
||||
|
||||
### Nope, Hasn't Been Asked Before
|
||||
|
||||
If you can't find anything in the existing issues, don't be shy about
|
||||
filing a new one.
|
||||
|
||||
You should be sure to include the version the project, as well as versions
|
||||
of related software. For example, be sure to include the Qubes release
|
||||
version (R2, R3) and specific version numbers of package causing problems
|
||||
(if known).
|
||||
If your issue is related to hardware, provide as many details as possible
|
||||
about the hardware, which could include using commandline tools such as
|
||||
`lspci`.
|
||||
|
||||
Project maintainers really appreciate thorough explanations. It usually
|
||||
helps them address the problem more quickly, so everyone wins!
|
||||
|
||||
Improving the Code
|
||||
------------------
|
||||
|
||||
The best way is to "Fork" the repo on GitHub. This will create a copy of
|
||||
the repo on your GitHub account.
|
||||
|
||||
Before you set out to improve the code, you should have a focused idea in
|
||||
mind of what you want to do.
|
||||
|
||||
Each commit should do one thing, and each PR should be one specific
|
||||
improvement. Each PR needs to be signed.
|
||||
|
||||
* [How can I contribute to the Qubes Project?](https://www.qubes-os.org/doc/ContributingHowto/)
|
||||
* [Developer Documentation](https://www.qubes-os.org/doc/)
|
||||
* [Package Release Workflow](https://github.com/QubesOS/qubes-builder/blob/master/doc/ReleaseManagerWorkflow.md)
|
||||
81
basics_dev/source-code.md
Normal file
81
basics_dev/source-code.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Source Code
|
||||
permalink: /doc/source-code/
|
||||
redirect_from:
|
||||
- /en/doc/source-code/
|
||||
- /doc/SourceCode/
|
||||
- /wiki/SourceCode/
|
||||
---
|
||||
|
||||
Qubes Source Code Repositories
|
||||
==============================
|
||||
|
||||
All the Qubes code is kept in Git repositories. We have divided the project into
|
||||
several components, each of which has its own separate repository, for example:
|
||||
|
||||
* `core-admin.git` -- The core Qubes infrastructure, responsible for VM
|
||||
management, VM templates, fs sharing, etc.
|
||||
* `gui-daemon.git` -- GUI virtualization, Dom0 side.
|
||||
* `gui-agent-linux.git` -- GUI virtualization, Linux VM side.
|
||||
* `linux-template-builder.git` -- Scripts and other files used to create Qubes
|
||||
template images.
|
||||
|
||||
All of our repositories are available under the [QubesOS GitHub account].
|
||||
|
||||
To clone a repository:
|
||||
|
||||
~~~
|
||||
git clone https://github.com/QubesOS/<repo_name>.git <repo_name>
|
||||
~~~
|
||||
|
||||
e.g.:
|
||||
|
||||
~~~
|
||||
git clone https://github.com/QubesOS/qubes-core-admin.git core-admin
|
||||
~~~
|
||||
|
||||
To clone **all** of our repositories in a single command:
|
||||
|
||||
~~~
|
||||
curl "https://api.github.com/orgs/QubesOS/repos?page=1&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone
|
||||
~~~
|
||||
|
||||
To update (git fetch) **all** of these repositories in a single command:
|
||||
|
||||
~~~
|
||||
find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \;
|
||||
~~~
|
||||
|
||||
(Alternatively, you can pull instead of just fetching.)
|
||||
|
||||
|
||||
How to Send Patches
|
||||
-------------------
|
||||
|
||||
If you want to contribute code to the project, there are two ways. Whichever
|
||||
method you choose, you must [sign your code] before it can be accepted.
|
||||
|
||||
* **Preferred**: Use GitHub's [fork & pull requests].
|
||||
* Send a patch to our developer [mailing list] (`git format-patch`).
|
||||
|
||||
1. Make all the changes in your working directory, i.e. edit files, move them
|
||||
around (you can use 'git mv' for this), etc.
|
||||
2. Add the changes and commit them (`git add`, `git commit`). Never mix
|
||||
different changes into one commit! Write a good description of the commit.
|
||||
The first line should contain a short summary, and then, if you feel like
|
||||
more explanations are needed, enter an empty new line, and then start the
|
||||
long, detailed description (optional).
|
||||
3. Test your changes NOW: check if RPMs build fine, etc.
|
||||
4. Create the patch using `git format-patch`. This has an advantage over
|
||||
`git diff`, because the former will also include your commit message, your
|
||||
name and email, so that *your* name will be used as a commit's author.
|
||||
5. Send your patch to `qubes-devel`. Start the message subject with
|
||||
`[PATCH]`.
|
||||
|
||||
|
||||
[QubesOS GitHub account]: https://github.com/QubesOS/
|
||||
[sign your code]: /doc/code-signing/
|
||||
[fork & pull requests]: https://guides.github.com/activities/forking/
|
||||
[mailing list]: /doc/mailing-lists/
|
||||
|
||||
93
basics_dev/style-guide.md
Normal file
93
basics_dev/style-guide.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Style-guide
|
||||
permalink: /doc/style-guide/
|
||||
---
|
||||
|
||||
Style Guide
|
||||
===========
|
||||
|
||||
## Fonts
|
||||
|
||||
Currently Qubes OS is using the following fonts for our website, branding, and other public facing (non-OS) materials. The OS itself uses what is normal for a users desktop environment of choice.
|
||||
|
||||
<div class="styleguide">
|
||||
{% for font in site.data.styleguide.fonts %}
|
||||
<div class="row">
|
||||
<div class="col-lg-6 col-md-6 focus">
|
||||
<div class="font {{font.class}}">Custom Qubes Font</div>
|
||||
</div>
|
||||
<div class="col-lg-6 col-md-6">
|
||||
<strong>Family:</strong> {{font.family}}<br>
|
||||
</div>
|
||||
</div>
|
||||
{% endfor %}
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Colors
|
||||
|
||||
The following **grayscale** colors are currently used on the Qubes website, documentation, and will eventually match colors within the OS itself.
|
||||
|
||||
<div class="styleguide">
|
||||
{% for color in site.data.styleguide.colors %}
|
||||
{% if color.type == "grayscale" %}
|
||||
<div class="swatch more-bottom more-right">
|
||||
<div class="color add-bottom bg-{{color.class}}"></div>
|
||||
<strong class="add-bottom">{{color.name}}</strong>
|
||||
<code>#{{color.hex}}</code>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</div>
|
||||
|
||||
The following **colors** are currently being used on the Qubes website, documentation, and will eventually match the colors within the OS itself!
|
||||
|
||||
<div class="styleguide">
|
||||
{% for color in site.data.styleguide.colors %}
|
||||
{% if color.type == "colors" %}
|
||||
<div class="swatch more-bottom more-right">
|
||||
<div class="color add-bottom bg-{{color.class}}"></div>
|
||||
<strong class="add-bottom">{{color.name}}</strong>
|
||||
<code>#{{color.hex}}</code>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Icons
|
||||
|
||||
Currently, all the icons on the Qubes-OS.org website are generated using [FontAwesome](http://fortawesome.github.io/Font-Awesome/).
|
||||
|
||||
*As more custom work is done to generate icons for the operating system itself, they will be added here!*
|
||||
|
||||
---
|
||||
|
||||
## Logos
|
||||
|
||||
The following is a collection of various sizes & 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).
|
||||
|
||||
<div class="styleguide">
|
||||
{% for logo in site.data.styleguide.logos %}
|
||||
{% for version in logo.versions %}
|
||||
<div class="row more-bottom">
|
||||
<div class="col-lg-4 col-md-4">
|
||||
<div class="focus">
|
||||
<img class="logo" src="{{version.path}}{{logo.image}}">
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-lg-8 col-md-8">
|
||||
<p>
|
||||
<strong>Image:</strong> {{logo.image}}<br>
|
||||
<strong>Size:</strong> {{version.size}}<br>
|
||||
<strong>Format:</strong> {{version.format}}<br>
|
||||
<strong>Download:</strong> <a href="{{version.path}}{{logo.image}}" target="_blank">this image</a>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</div>
|
||||
52
basics_dev/system-doc.md
Normal file
52
basics_dev/system-doc.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
layout: doc
|
||||
title: System Documentation
|
||||
permalink: /doc/system-doc/
|
||||
redirect_from:
|
||||
- /en/doc/system-doc/
|
||||
- /doc/SystemDoc/
|
||||
- /wiki/SystemDoc/
|
||||
---
|
||||
|
||||
System Documentation for Developers
|
||||
===================================
|
||||
|
||||
Fundamentals
|
||||
------------
|
||||
* [Qubes OS Architecture Overview](/doc/architecture/)
|
||||
* [Qubes OS Architecture Spec v0.3 [PDF]](/attachment/wiki/QubesArchitecture/arch-spec-0.3.pdf)
|
||||
(The original 2009 document that started this all...)
|
||||
* [Security-critical elements of Qubes OS](/doc/security-critical-code/)
|
||||
* [Qrexec: command execution in VMs](/doc/qrexec3/)
|
||||
* [Qubes GUI virtualization protocol](/doc/gui/)
|
||||
* [Networking in Qubes](/doc/networking/)
|
||||
* [Implementation of template sharing and updating](/doc/template-implementation/)
|
||||
|
||||
Services
|
||||
--------
|
||||
* [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 disposable VMs](http://theinvisiblethings.blogspot.com/2010/06/disposable-vms.html)
|
||||
* [Dom0 secure update mechanism](/doc/dom0-secure-updates/)
|
||||
* VM secure update mechanism (forthcoming)
|
||||
|
||||
Debugging
|
||||
---------
|
||||
* [Profiling python code](/doc/profiling/)
|
||||
* [Test environment in separate machine for automatic tests](/doc/test-bench/)
|
||||
* [Automated tests](/doc/automated-tests/)
|
||||
* [VM-dom0 internal configuration interface](/doc/vm-interface/)
|
||||
* [Debugging Windows VMs](/doc/windows-debugging/)
|
||||
|
||||
Building
|
||||
--------
|
||||
* [Building Qubes](/doc/qubes-builder/) (["API" Details](/doc/qubes-builder-details/))
|
||||
* [Development Workflow](/doc/development-workflow/)
|
||||
* [KDE Dom0 packages for Qubes](/doc/kde-dom0/)
|
||||
* [Building Qubes OS 3.0 ISO](/doc/qubes-r3-building/)
|
||||
* [Building USB passthrough support (experimental)](/doc/pvusb/)
|
||||
* [Building a TemplateVM based on a new OS (ArchLinux example)](/doc/building-non-fedora-template/)
|
||||
* [Building the Archlinux Template](/doc/building-archlinux-template/)
|
||||
|
||||
|
||||
232
basics_dev/usability-ux.md
Normal file
232
basics_dev/usability-ux.md
Normal file
|
|
@ -0,0 +1,232 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Usability & UX
|
||||
permalink: /doc/usability-ux/
|
||||
---
|
||||
|
||||
Usability & UX
|
||||
==============
|
||||
|
||||
Software that is too complicated to use, is often unused. Thus, usability and user experience of Qubes OS is an utmost priority for us, as we want as many people as possible to benefit from the unique security properties of Qubes OS!
|
||||
|
||||
We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. Also, please review [our style guide](/doc/style-guide/) for other design related information.
|
||||
|
||||
---
|
||||
|
||||
## Easy To Use
|
||||
|
||||
An ideal user experience is friendly and welcomes a new user to explore the interface and in this process easily discover *how* to use the software. Additionally, security focused software has the responsibility of providing safety to a user and their data.
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong>Interfaces Should Not</strong>
|
||||
</div>
|
||||
|
||||
- Require numerous settings to be entered before a user can *begin* doing things
|
||||
- Make it possible to break provided features or actions in unrecoverable ways
|
||||
- Perform actions which compromise security and data
|
||||
- Overwhelm with too much information and cognitive load
|
||||
|
||||
Perhaps the most common cause of mistakes is complexity. Thus, if there is a configuration setting that will significantly affect the user experience, choose a safe and smart default then tuck this setting in an `Advanced Settings` panel.
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong>Interfaces Should</strong>
|
||||
</div>
|
||||
|
||||
- Make it easy to discover features and available actions
|
||||
- Provide some understanding of what discovered features do
|
||||
- Offer the ability to easily undo mistakes
|
||||
- Choose intelligent defaults for settings
|
||||
|
||||
A crucial thing in making software easy to use, is being mindful of [cognitive load](https://en.wikipedia.org/wiki/Cognitive_load) which dictates that *"humans are generally able to hold only seven +/- two units of information in short-term memory."* This short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Easy to Understand
|
||||
|
||||
There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this- none these are absolute maxims!
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong>Avoid Acronyms</strong>
|
||||
</div>
|
||||
|
||||
Acronyms are short and make good names for command line tools. Acronyms do not make graphical user interfaces more intuitive for non-technical users. Until one learns an acronyms meaning, it is otherwise meaningless. Avoid acronyms whenever possible!
|
||||
|
||||
- `DVM` - Disposable Virtual Machine
|
||||
- `GUID` - Global Unique Identifier
|
||||
- `PID` - Process Identification
|
||||
- `NetVM` - Networking Virtual Machine
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong> Use Simple Words</strong>
|
||||
</div>
|
||||
|
||||
Use the minimum amount of words needed to be descriptive, but also informative. Go with common words that are as widely understood as possible. Sometimes, inventing a word such as `Qube` to describe a `virutal machine` in the context of Qubes OS, is a good idea.
|
||||
|
||||
- Use `Disposable Qube` instead of `DVM`
|
||||
- Use `interface` instead of `GUI`
|
||||
- Use `application` instead of `PID`
|
||||
- Use `Networking` or `Networking Qube` instead of `NetVM` given context
|
||||
|
||||
However, acronyms like `USB` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms, as the full words `Universal Serial Bus` is more likely to confuse users.
|
||||
|
||||
---
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong> Avoid Technical Words</strong>
|
||||
</div>
|
||||
|
||||
Technical words are usually more accurate, but they often *only* make sense to technical users and are confusing and unhelpful to non-technical users. Examples of technical words that might show up in Qubes OS are:
|
||||
|
||||
- `root.img`
|
||||
- `savefile`
|
||||
- `qrexec-daemon`
|
||||
|
||||
These are all terms that have at some point showed up in notification messages presented users. Each term is very accurate, but requires understanding virtualization
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong> Use Common Concepts</strong>
|
||||
</div>
|
||||
|
||||
Large amounts of the global population have been using computers for one or two decades and have formed some mental models of how things work. Leveraging these mental models are a huge gain.
|
||||
|
||||
- Use `disk space` instead of `root.img` while not quite accurate, it makes contextual sense
|
||||
- Use`saving` instead of `savefile` as the former is the action trying to be completed
|
||||
- Use `Qubes` instead of `qrexec-daemon` as it is the larger context what is happening
|
||||
|
||||
These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes).
|
||||
|
||||
---
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong>Avoid Inconsistencies</strong>
|
||||
</div>
|
||||
|
||||
It is easy to start abbreviating (or making acronyms) of long terms like `Disposable Virtual Machine` depending on where the term shows up in an interface.
|
||||
|
||||
- `DVM`
|
||||
- `DispVM`
|
||||
- `DisposableVM`
|
||||
|
||||
This variation in terms can cause new users to question or second guess what the three different variations mean, which can lead to inaction or mistakes.
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong> Make Things Consistent</strong>
|
||||
</div>
|
||||
|
||||
Always strive to keep things consistent in the interfaces as well as documentation and other materials.
|
||||
|
||||
- Use `Disposable Qube` at all times as it meets other criteria as well.
|
||||
|
||||
By using the same term throughout an interface, a user can create a mental model and relationship with that term allowing them to feel empowered.
|
||||
|
||||
---
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong>Avoid Duplicate Words</strong>
|
||||
</div>
|
||||
|
||||
It is easy when trying to be descriptive and accurate to add words like `Domain` before items in a list or menu such as:
|
||||
|
||||
~~~
|
||||
Menu
|
||||
- Domain: work
|
||||
- Domain: banking
|
||||
- Domain: personal
|
||||
~~~
|
||||
|
||||
The repeated use of the word `Domain` requires a user to read it for each item in the list, which takes extra time for the eye to parse out the relevant word like `work, banking, or personal`. This also affects horizontal space on fixed width lines.
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong> Create Groups & Categories</strong>
|
||||
</div>
|
||||
|
||||
It is more efficient to group things under headings like `Domains` as this allows the eye to easily scan the uniqueness of the items.
|
||||
|
||||
~~~
|
||||
Domains
|
||||
- Work
|
||||
- Banking
|
||||
- Personal
|
||||
~~~
|
||||
|
||||
---
|
||||
|
||||
## Easy To Complete
|
||||
|
||||
Lastly, expected (and unexpected) situations will happen which require user actions or input. Make resolving of these actions as easy as possible to complete the action or find.
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong>Don't Leave Users Stranded</strong>
|
||||
</div>
|
||||
|
||||
Consider the following notifications which are shown to a user:
|
||||
|
||||
- `The disk space of your Qube "Work" is full`
|
||||
- `There was an error saving Qube "Personal"`
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong> Offer Actionable Solutions</strong>
|
||||
</div>
|
||||
|
||||
An error message or limit such as that can be greatly improved upon by adding buttons or links to helpful information.
|
||||
|
||||
- Add a button `Increase Disk Space`
|
||||
- Add a link to documentation `Troubleshoot saving data`
|
||||
|
||||
Adhering to these principles, make undesirable situations more manageable for users instead of feeling stranded.
|
||||
|
||||
---
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-times"></i> <strong>Avoid Repetitive Tasks</strong>
|
||||
</div>
|
||||
|
||||
There are many cases where a user wants to perform an action on more than one file or folder. However in order to do the action, the user must repeat certain steps such as:
|
||||
|
||||
1. Click on `Open File` from a menu or button
|
||||
2. Navigate through file system
|
||||
- Click Folder One
|
||||
- Click Folder Two
|
||||
- Click Folder Three
|
||||
- Click Folder Four
|
||||
3. Select proper file
|
||||
4. Complete task on file
|
||||
|
||||
That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couples files in the same directory.
|
||||
|
||||
<div class="focus">
|
||||
<i class="fa fa-check"></i> <strong>Minimize Repetitive Steps</strong>
|
||||
</div>
|
||||
|
||||
1. Click on `Open File` from a menu or button
|
||||
2. Remember last open file system
|
||||
3. Select proper file
|
||||
4. Complete task
|
||||
|
||||
Clearly, cutting out navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item `Open Multiple Files` could be even better, as using hot keys to select multiple files is often a thing only power users know how to do!
|
||||
|
||||
---
|
||||
|
||||
## GNOME, KDE, and Xfce
|
||||
|
||||
The the desktop GUIs which QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org), as well as [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, however, we believe the overalluser experience of GNOME is more focused on simplicity and ease of use for average non-technical users. Xfce will always be supported, and technical users will always be able to still use KDE or other desktop environments.
|
||||
|
||||
All three desktop environments have their own [human interface guidelines](https://en.wikipedia.org/wiki/Human_interface_guidelines) and we suggest you familiarize yourself with the platform you developing for.
|
||||
|
||||
- [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/3.18/)
|
||||
- [KDE HIG](https://techbase.kde.org/Projects/Usability/HIG)
|
||||
- [Xfce UI Guidlines](https://wiki.xfce.org/dev/hig/general)
|
||||
|
||||
---
|
||||
|
||||
## Further Learning & Inspiration
|
||||
|
||||
Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding of usability and experience, we suggest the following resources.
|
||||
|
||||
- [Learn Design Principles](http://learndesignprinciples.com) by Melissa Mandelbaum
|
||||
- [Usability in Free Software](http://jancborchardt.net/usability-in-free-software) by Jan C. Borchardt
|
||||
- [Superheroes & Villains in Design](https://vimeo.com/70030549) by Aral Balkan
|
||||
- [First Rule of Usability? Don’t Listen to Users](http://www.nngroup.com/articles/first-rule-of-usability-dont-listen-to-users/) by by Jakob Nielsen
|
||||
- [10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/) by Jakob Nielsen
|
||||
- [Hack Design](https://hackdesign.org/) - online learning program
|
||||
Loading…
Add table
Add a link
Reference in a new issue