Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-08-09 07:02:30 -04:00
Code Issues Projects Releases Packages Wiki Activity

Reorganize files to account for new "External" section

Browse source 
QubesOS/qubes-issues#4693
This commit is contained in:
Andrew David Wong 2019-05-26 19:32:45 -05:00
parent 5cc99a23d1
commit d31c786942
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
203 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

29
developer/general/devel-books.md Normal file
View 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:
* _[The Definitive Guide to the Xen Hypervisor](https://www.amazon.com/Definitive-Guide-Xen-Hypervisor/dp/013234971X)_, by David Chisnall
- Some good books about the Linux kernel:
* _[Linux Kernel Development](https://www.amazon.com/Linux-Kernel-Development-Robert-Love/dp/0672329468)_, by Robert Love
* _[Linux Device Drivers](https://www.amazon.com/Linux-Device-Drivers-Jonathan-Corbet/dp/0596005903)_, by Jonathan Corbet
- Solid intro into Trusted Computing:
* _[Dynamics of a Trusted Platform](https://www.amazon.com/Dynamics-Trusted-Platform-Buildin-Grawrock/dp/1934053082)_, by David Grawrock (original Intel architect for TXT)
- Good book about GIT:
* _[Pro Git](https://git-scm.com/book/en/v2)_, by Scott Chacon and Ben Straub (complete book available free online)
- Useful books about Python:
* _[Programming in Python 3](http://www.qtrac.eu/py3book.html)_, by Mark Summerfield
* _[Rapid GUI Programming with Python and Qt](http://www.qtrac.eu/pyqtbook.html)_, by Mark Summerfield
(Although note that [Qt is being replaced by GTK](/doc/usability-ux/#gnome-kde-and-xfce) in Qubes code.)

308
developer/general/doc-guidelines.md Normal file
View file

@ -0,0 +1,308 @@
---
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. Volunteers work hard trying to keep everything accurate and comprehensive.
If you notice a problem or some way it can be improved, please [edit the documentation][contribute]!
Questions, problems, and improvements
-------------------------------------
If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself.
To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue].
(If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
How to Contribute
-----------------
Editing the documentation is easy, so if you see that a change should be made, please contribute it!
A few notes before we get started:
* Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted.
This allows us to maintain quality control and protect our users.
* We don't want you to spend time and effort on a contribution that we can't accept.
If your contribution would take a lot of time, please [file an issue][issue] for it first so that we can make sure we're on the same page before significant works begins.
* Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does.
In this case, you can still submit it by following the instructions below.
Just make a note in your pull request that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes.
As mentioned above, we keep all the documentation in a dedicated [Git repository][qubes-doc] hosted on [GitHub].
Thanks to GitHub's 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 side (in the desktop layout):
![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png)
Or at the bottom (in the mobile layout):
![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png)
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.
![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png)
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.
![fork](/attachment/wiki/doc-edit/05-fork.png)
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.
If you're making formatting changes, please [render the site locally] to verify that everything looks correct before submitting any changes.
![edit](/attachment/wiki/doc-edit/06-edit.png)
Once you're finished, describe your changes at the bottom and click "Propose file change".
![commit](/attachment/wiki/doc-edit/07-commit-msg.png)
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.
![pull-request](/attachment/wiki/doc-edit/08-review-changes.png)
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.
![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png)
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.
![done](/attachment/wiki/doc-edit/10-done.png)
How to add images
-----------------
To add an image to a page, use the following syntax in the main document:
```
![Image Title](/attachment/wiki/page-title/image-filename.png)
```
Then, submit your image(s) in a separate pull request to the [qubes-attachment] repository using the same path and filename.
Version-specific Documentation
------------------------------
We maintain only one set of documentation for Qubes OS.
We do not maintain a different set of documentation for each version of Qubes.
Our single set of Qubes OS documentation is updated on a continual, rolling basis.
Our first priority is to document all **current, stable releases** of Qubes.
Our second priority is to document the next, upcoming release (if any) that is currently in the beta or release candidate stage.
In cases where a documentation page covers functionality that differs considerably between Qubes OS versions, the page should be subdivided into clearly-labeled sections that cover the different functionality in different versions:
### Incorrect Example ###
```
# Page Title #
## How to Foo ##
Fooing is the process by which one foos. There are both general and specific
versions of fooing, which vary in usefulness depending on your goals, but for
the most part, all fooing is fooing.
To foo in Qubes 3.2:
$ qvm-foo <foo-bar>
Note that this does not work in Qubes 4.0, where there is a special widget
for fooing, which you can find in the lower-right corner of the screen in
the Foo Manager. Alternatively, you can use the more general `qubes-baz`
command introduced in 4.0:
$ qubes-baz --foo <bar>
Once you foo, make sure to close the baz before fooing the next bar.
```
### Correct Example ###
```
# Page Title #
## Qubes 3.2 ##
### How to Foo ###
Fooing is the process by which one foos. There are both general and specific
versions of fooing, which vary in usefulness depending on your goals, but for
the most part, all fooing is fooing.
To foo:
$ qvm-foo <foo-bar>
Once you foo, make sure to close the baz before fooing the next bar.
## Qubes 4.0 ##
### How to Foo ###
Fooing is the process by which one foos. There are both general and specific
versions of fooing, which vary in usefulness depending on your goals, but for
the most part, all fooing is fooing.
There is a special widget for fooing, which you can find in the lower-right
corner of the screen in the Foo Manager. Alternatively, you can use the
general `qubes-baz` command:
$ qubes-baz --foo <bar>
Once you foo, make sure to close the baz before fooing the next bar.
```
Subdividing the page into clearly-labeled sections for each version has several benefits:
* It preserves good content for older (but still supported) versions.
Many documentation contributors are also people who prefer to use the latest version.
Many of them are tempted to *replace* existing content that applies to an older, supported version with content that applies only to the latest version.
This is somewhat understandable.
Since they only use the latest version, they may be focused on their own experience, and they may even regard the older version as deprecated, even when it's actually still supported.
However, allowing this replacement of content would do a great disservice to those who still rely on the older, supported version.
In many cases, these users value the stability and reliability of the older, supported version.
With the older, supported version, there has been more time to fix bugs and make improvements in both the software and the documentation.
Consequently, much of the documentation content for this version may have gone through several rounds of editing, review, and revision.
It would be a tragedy for this content to vanish while the very set of users who most prize stability and reliability are depending on it.
* It's easy for readers to quickly find the information they're looking for, since they can go directly to the section that applies to their version.
* It's hard for readers to miss information they need, since it's all in one place.
In the incorrect example, information that the reader needs could be in any paragraph in the entire document, and there's no way to tell without reading the entire page.
In the correct example, the reader can simply skim the headings in order to know which parts of the page need to be read and which can be safely ignored.
The fact that some content is repeated in the two version-specific sections is not a problem, since no reader has to read the same thing twice.
Moreover, as one version gets updated, it's likely that the documentation for that version will also be updated.
Therefore, content that is initially duplicated between version-specific sections will not necessarily stay that way, and this is a good thing:
We want the documentation for a version that *doesn't* change to stay the same, and we want the documentation for a version that *does* change to change along with the software.
* It's easy for documentation contributors and maintainers to know which file to edit and update, since there's only one page for all Qubes OS versions.
Initially creating the new headings and duplicating content that applies to both is only a one-time cost for each page, and many pages don't even require this treatment, since they apply to all currently-supported Qubes OS versions.
By contrast, an alternative approach, such as segregating the documentation into two different branches, would mean that contributions that apply to both Qubes versions would only end up in one branch, unless someone remembered to manually submit the same thing to the other branch and actually made the effort to do so.
Most of the time, this wouldn't happen.
When it did, it would mean a second pull request that would have to be reviewed.
Over time, the different branches would diverge in non-version-specific content.
Good general content that was submitted only to one branch would effectively disappear once that version was deprecated.
(Even if it were still on the website, no one would look at it, since it would explicitly be in the subdirectory of a deprecated version, and there would be a motivation to remove it from the website so that search results wouldn't be populated with out-of-date information.)
For further discussion about version-specific documentation in Qubes, see [here][version-thread].
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.
* In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo.
Examples of exceptions:
* [QSBs] (intended to be read as plain text)
* [News] posts (plain text is reproduced on the [mailing lists][support])
* URLs that appear inside code blocks (e.g., in comments and document templates)
* Files like `README.md` and `CONTRIBUTING.md`
* Insert a newline at, and only at, the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
* Rationale: This practice results in one sentence per line, which is most appropriate for source that consists primarily of natural language text.
It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability.
* 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 ###`).
* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* When providing command line examples:
* Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
$ cd test
$ echo Hello
Hello
```
~~~
* Precede each command with the appropriate command prompt:
At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
* Don't try to add comments inside the code block.
For example, *don't* do this:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
# Navigate to the new directory
$ cd test
# Generate a greeting
$ echo Hello
Hello
```
~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
* 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 try to write good commit messages, according to the
[instructions in our coding style guidelines][git-commit].
[qubes-doc]: https://github.com/QubesOS/qubes-doc
[glossary]: /doc/glossary/
[issue]: /doc/reporting-bugs/
[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/
[support]: /support/
[version-example]: /doc/template/fedora/upgrade-25-to-26/
[version-thread]: https://groups.google.com/d/topic/qubes-users/H9BZX4K9Ptk/discussion
[QSBs]: /security/bulletins/
[News]: /news/
[md]: https://daringfireball.net/projects/markdown/
[git-commit]: /doc/coding-style/#commit-message-guidelines
[render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions
[qubes-attachment]: https://github.com/QubesOS/qubes-attachment

628
developer/general/gsoc.md Normal file
View file

@ -0,0 +1,628 @@
---
layout: sidebar
title: Google Summer of Code
permalink: /gsoc/
redirect_from: /GSoC/
---
2019 Google Summer of Code
================
## Information for Students
Thank you for your interest in participating in the [Google Summer of Code program][gsoc-qubes] with the [Qubes OS team][team]. You can read more about the Google Summer of Code program at the [official website][gsoc] and the [official FAQ][gsoc-faq].
Being accepted as a Google Summer of Code student is quite competitive. Students wishing to participate in the Summer of Code must be aware that you will be required to produce code for Qubes OS for 3 months. Your mentors, Qubes developers, will dedicate a portion of their time towards mentoring you. Therefore, we seek candidates who are committed to helping Qubes long-term and are willing to do quality work and be proactive in communicating with your mentor.
You don't have to be a proven developer -- in fact, this whole program is meant to facilitate joining Qubes and other free and open source communities. The Qubes community maintains information about [contributing to Qubes development][contributing] and [how to send patches][patches]. In order to contribute code to the Qubes project, you must be able to [sign your code][code-signing].
You should start learning the components that you plan on working on before the start date. Qubes developers are available on the [mailing lists][ml-devel] for help. The GSoC timeline reserves a lot of time for bonding with the project -- use that time wisely. Good communication is key, you should plan to communicate with your team daily and formally report progress and plans weekly. Students who neglect active communication will be failed.
You can view the projects we had in 2017 in the [GSoC archive here][2017-archive].
### Overview of Steps
- Join the [qubes-devel list][ml-devel] and introduce yourself, and meet your fellow developers
- Read [Google's instructions for participating][gsoc-participate] and the [GSoC Student Manual][gsoc-student]
- Take a look at the list of ideas below
- Come up with a project that you are interested in (and feel free to propose your own! Don't feel limited by the list below.)
- Read the Student Proposal guidelines below
- Write a first draft proposal and send it to the qubes-devel mailing list for review
- Submit proposal using [Google's web interface][gsoc-submit] ahead of the deadline (this requires a Google Account!)
- Submit proof of enrollment well ahead of the deadline
Coming up with an interesting idea that you can realistically achieve in the time available to you (one summer) is probably the most difficult part. We strongly recommend getting involved in advance of the beginning of GSoC, and we will look favorably on applications from students who have already started to act like free and open source developers.
Before the summer starts, there are some preparatory tasks which are highly encouraged. First, if you aren't already, definitely start using Qubes as your primary OS as soon as possible! Also, it is encouraged that you become familiar and comfortable with the Qubes development workflow sooner than later. A good way to do this (and also a great way to stand out as an awesome applicant and make us want to accept you!) might be to pick up some issues from [qubes-issues][qubes-issues] (our issue-tracking repo) and submit some patches addressing them. Some suitable issues might be those with tags ["help wanted" and "P: minor"][qubes-issues-suggested] (although more significant things are also welcome, of course). Doing this will get you some practice with [qubes-builder][qubes-builder], our code-signing policies, and some familiarity with our code base in general so you are ready to hit the ground running come summer.
### Student proposal guidelines
A project proposal is what you will be judged upon. Write a clear proposal on what you plan to do, the scope of your project, and why we should choose you to do it. Proposals are the basis of the GSoC projects and therefore one of the most important things to do well. The proposal is not only the basis of our decision of which student to choose, it has also an effect on Google's decision as to how many student slots are assigned to Qubes.
Below is the application template:
```
# Introduction
Every software project should solve a problem. Before offering the solution (your Google Summer of Code project), you should first define the problem. What’s the current state of things? What’s the issue you wish to solve and why? Then you should conclude with a sentence or two about your solution. Include links to discussions, features, or bugs that describe the problem further if necessary.
# Project goals
Be short and to the point, and perhaps format it as a list. Propose a clear list of deliverables, explaining exactly what you promise to do and what you do not plan to do. “Future developments” can be mentioned, but your promise for the Google Summer of Code term is what counts.
# Implementation
Be detailed. Describe what you plan to do as a solution for the problem you defined above. Include technical details, showing that you understand the technology. Illustrate key technical elements of your proposed solution in reasonable detail.
# Timeline
Show that you understand the problem, have a solution, have also broken it down into manageable parts, and that you have a realistic plan on how to accomplish your goal. Here you set expectations, so don’t make promises you can’t keep. A modest, realistic and detailed timeline is better than promising the impossible.
If you have other commitments during GSoC, such as a job, vacation, exams, internship, seminars, or papers to write, disclose them here. GSoC should be treated like a full-time job, and we will expect approximately 40 hours of work per week. If you have conflicts, explain how you will work around them. If you are found to have conflicts which you did not disclose, you may be failed.
Open and clear communication is of utmost importance. Include your plans for communication in your proposal; daily if possible. You will need to initiate weekly formal communications such as a detailed email to the qubes-devel mailing list. Lack of communication will result in you being failed.
# About me
Provide your contact information and write a few sentences about you and why you think you are the best for this job. Prior contributions to Qubes are helpful; list your commits. Name people (other developers, students, professors) who can act as a reference for you. Mention your field of study if necessary. Now is the time to join the relevant mailing lists. We want you to be a part of our community, not just contribute your code.
Tell us if you are submitting proposals to other organizations, and whether or not you would choose Qubes if given the choice.
Other things to think about:
* Are you comfortable working independently under a supervisor or mentor who is several thousand miles away, and perhaps 12 time zones away? How will you work with your mentor to track your work? Have you worked in this style before?
* If your native language is not English, are you comfortable working closely with a supervisor whose native language is English? What is your native language, as that may help us find a mentor who has the same native language?
* After you have written your proposal, you should get it reviewed. Do not rely on the Qubes mentors to do it for you via the web interface, although we will try to comment on every proposal. It is wise to ask a colleague or a developer to critique your proposal. Clarity and completeness are important.
```
## Project Ideas
These project ideas were contributed by our developers and may be incomplete. If you are interested in submitting a proposal based on these ideas, you should contact the [qubes-devel mailing list][ml-devel] and associated GitHub issue to learn more about the idea.
```
### Adding a Proposal
**Project**: Something that you're totally excited about
**Brief explanation**: What is the project, where does the code live?
**Expected results**: What is the expected result in the timeframe given
**Knowledge prerequisite**: Pre-requisites for working on the project. What coding language and knowledge is needed?
If applicable, links to more information or discussions
**Mentor**: Name and email address.
```
### Template manager, new template distribution mechanism
**Project**: Template manager, new template distribution mechanism
**Brief explanation**: Template VMs currently are distributed using RPM
packages. There are multiple problems with that, mostly related to static
nature of RPM package (what files belong to the package). This means such
Template VM cannot be renamed, migrated to another storage (like LVM), etc.
Also we don't want RPM to automatically update template package itself (which
would override all the user changes there). More details:
[#2064](https://github.com/QubesOS/qubes-issues/issues/2064),
[#2534](https://github.com/QubesOS/qubes-issues/issues/2534).
**Expected results**:
- Design new mechanism for distributing templates (possibly including some
package format - either reuse something already existing, or design
new one). The mechanism needs to handle:
- integrity protection (digital signatures), not parsing any data in dom0
prior to signature verification
- efficient handling of large sparse files
- ability to deploy the template into various storage mechanisms (sparse
files, LVM thin volumes etc).
- template metadata, templates repository - enable the user to browse
available templates (probably should be done in dedicated VM, or DisposableVM)
- Implement the above mechanism:
- tool to download named template - should perform download operation in
some VM (as dom0 have no network access), then transfer the data to dom0,
verify its integrity and then create Template VM and feed it's root
filesystem image with downloaded data.
- tool to browse templates repository - both CLI and GUI (preferably in (py)GTK)
- integrate both tools - user should be able to choose some template to be
installed from repository browsing tool - see
[#1705](https://github.com/QubesOS/qubes-issues/issues/1705) for some idea
(this one lack integrity verification, but similar service could
be developed with that added)
- If new "package" format is developed, add support for it into
[linux-template-builder](https://github.com/QubesOS/qubes-linux-template-builder).
- Document the mechanism.
- Write unit tests and integration tests.
**Knowledge prerequisite**:
- Large files (disk images) handling (sparse files, archive formats)
- Bash and Python scripting
- Data integrity handling - digital signatures (gpg2, gpgv2)
- PyGTK
- RPM package format, (yum) repository basics
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### USB passthrough to Windows qubes
**Project**: USB passthrough to Windows qubes
**Brief explanation**: Add ability to use individual USB devices in Windows qubes. Right now the only option to do that, is to assign the whole USB controller (PCI device), which applies to all the devices connected to it. USB passthrough on Qubes is based on USBIP project, with transport over qrexec instead of TCP/IP.
**Expected results**:
- Evaluate possible approaches (including flexibility, compatibility and performance), suggested ideas:
- use [USBIP for Windows](https://github.com/cezuni/usbip-win) and make it work with qrexec - similar as done for Linux
- use qrexec+USBIP in Linux-based stubdomain and plug it into USB emulation in qemu
- Choose one approach, write (very simple) design documentation
- Write relevant new code (applies mostly for usbip-win case)
- Plug the mechanism into Qubes core toolstack ([Devices API](https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-devices.html))
**Knowledge prerequisite**:
- basic USB architecture knowledge (buses, devices, interfaces, functions)
- Python and Bash scripting
- C
- Windows USB stack and/or qemu USB stack
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Dedicated Audio qube
**Project**: Dedicated Audio qube
**Brief explanation**: Moving audio subsystem from dom0 to a dedicated AudioVM and/or a preexisting VM (e.g sys-usb with attached usb audio device). This would allow using USB audio devices system-wide, without leaving a USB controller in dom0. [Relevant github issue](https://github.com/QubesOS/qubes-issues/issues/1590).
**Expected results**:
- Make audio virtualization components work with non-dom0 backend (in short: add configuration option for the backend, instead of assuming "dom0")
- Possibly per-qube setting what should be used as an AudioVM
- Make other audio-related tools work with the new setup, especially enabling/disabling microphone (`qvm-device mic`) and volume control.
**Knowledge prerequisite**:
- Pulseaudio
- C
- Python
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Qubes as a Vagrant provider
**Project**: Qubes as a Vagrant provider
**Brief explanation**: Currently using Vagrant on Qubes requires finding an image that uses Docker as isolation provider and running Docker in a qube, or downloading the Vagrantfile and manually setting up a qube according to the Vagrantfile. This project aims at simplifying this workflow. Since introduction of Admin API, it's possible for a qube to provision another qube - which is exactly what is needed for Vagrant. [Related discussion](https://groups.google.com/d/msgid/qubes-devel/535299ca-d16a-4a70-8223-a4ac6be4be41%40googlegroups.com)
**Expected results**:
- Design how Vagrant Qubes provider should look like, including:
- [box format](https://www.vagrantup.com/docs/plugins/providers.html#box-format)
- method for running commands inside (ssh vs qvm-run)
- Write a Vagrant provider able to create/start/stop/etc a VM
- Document how to configure and use the provider, including required qrexec policy changes and possibly firewall rules
- Write integration tests
**Knowledge prerequisite**:
- Ruby
- Vagrant concepts
**Mentor**: [Wojtek Porczyk](/team/), [Marek Marczykowski-Górecki](/team/)
### Mechanism for maintaining in-VM configuration
**Project**: Mechanism for maintaining in-VM configuration
**Brief explanation**: Large number of VMs is hard to maintain. Templates helps with keeping them updated, but many applications have configuration in user home directory, which is not synchronized.
**Expected results**:
- Design a mechanism how to _safely_ synchronize application configuration living in user home directory (`~/.config`, some other "dotfiles"). Mechanism should be resistant against malicious VM forcing its configuration on other VMs. Some approach could be a strict control which VM can send what changes (whitelist approach, not blacklist).
- Implementation of the above mechanism.
- Documentation how to configure it securely.
**Knowledge prerequisite**:
- shell and/or python scripting
- Qubes OS qrexec services
**Mentor**: [Frédéric Pierret](/team/)
### Wayland support in GUI agent and/or GUI daemon
**Project**: Wayland support in GUI agent and/or GUI daemon
**Brief explanation**: Currently both GUI agent (VM side of the GUI virtualization) and GUI daemon (dom0 side of GUI virtualization) support X11 protocol only. It may be useful to add support for Wayland there. Note that those are in fact two independent projects:
1. GUI agent - make it work as Wayland compositor, instead of extracting window's composition buffers using custom X11 driver
2. GUI daemon - act as Wayland application, showing windows retrieved from VMs, keeping zero-copy display path (window content is directly mapped from application running in VM, not copied)
**Expected results**:
Choose either of GUI agent, GUI daemon. Both are of similar complexity and each separately looks like a good task for GSoC time period.
- design relevant GUI agent/daemon changes, the GUI protocol should not be affected
- consider window decoration handling - VM should have no way of spoofing those, so it must be enforced by GUI daemon (either client-side - by GUI daemon itself, or server-side, based on hints given by GUI daemon)
- implement relevant GUI agent/daemon changes
- implement tests for new GUI handling, similar to existing tests for X11 based GUI
Relevant links:
- [Low level GUI documentation](/doc/gui/)
- [qubes-gui-agent-linux](https://github.com/qubesos/qubes-gui-agent-linux)
- [qubes-gui-daemon](https://github.com/qubesos/qubes-gui-daemon)
- [Use Wayland instead of X11 to increase performance](https://github.com/qubesos/qubes-issues/issues/3366)
**Knowledge prerequisite**:
- Wayland architecture
- basics of X11 (for understanding existing code)
- C language
- using shared memory (synchronization methods etc)
**Mentor**: [Marek Marczykowski-Górecki](/team/).
### Qubes Live USB
**Project**: Revive Qubes Live USB, integrate it with installer
**Brief explanation**: Qubes Live USB is based on Fedora tools to build live
distributions. But for Qubes we need some adjustments: starting Xen instead of
Linux kernel, smarter copy-on-write handling (we run there multiple VMs, so a
lot more data to save) and few more. Additionally in Qubes 3.2 we have
so many default VMs that default installation does not fit in 16GB image
(default value) - some subset of those VMs should be chosen. Ideally we'd like
to have just one image being both live system and installation image. More
details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552),
[#1965](https://github.com/QubesOS/qubes-issues/issues/1965).
**Expected results**:
- Adjust set of VMs and templates included in live edition.
- Update and fix build scripts for recent Qubes OS version.
- Update startup script to mount appropriate directories as either
copy-on-write (device-mapper snapshot), or tmpfs.
- Optimize memory usage: should be possible to run sys-net, sys-firewall, and
at least two more VMs on 4GB machine. This include minimizing writes to
copy-on-write layer and tmpfs (disable logging etc).
- Research option to install the system from live image. If feasible add
this option.
**Knowledge prerequisite**:
- System startup sequence: bootloaders (isolinux, syslinux, grub, UEFI), initramfs, systemd.
- Python and Bash scripting
- Filesystems and block devices: loop devices, device-mapper, tmpfs, overlayfs, sparse files.
**Mentor**: [Frédéric Pierret](/team/)
### Unikernel-based firewallvm with Qubes firewall settings support
**Project**: Unikernel based firewallvm with Qubes firewall settings support
**Brief explanation**: [blog post](http://roscidus.com/blog/blog/2016/01/01/a-unikernel-firewall-for-qubesos/), [repo](https://github.com/talex5/qubes-mirage-firewall)
**Expected results**: A firewall implemented as a unikernel which supports all the networking-related functionality as the default sys-firewall VM, including configuration via Qubes Manager. Other duties currently assigned to sys-firewall such as the update proxy may need to be appropriately migrated first.
**Knowledge prerequisite**:
- [OCaml](https://ocaml.org/) + [MirageOS](https://mirage.io/) or other unikernel framework,
- Xen network stack,
- Qubes networking model & firewall semantics.
**Mentor**: [Thomas Leonard](mailto:talex5@gmail.com), [Marek Marczykowski-Górecki](/team/)
### LogVM(s)
**Project**: LogVM(s)
**Brief explanation**: Qubes AppVMs do not have persistent /var (on purpose).
It would be useful to send logs generated by various VMs to a dedicated
log-collecting VM. This way logs will not only survive VM shutdown, but also be
immune to altering past entries. See
[#830](https://github.com/QubesOS/qubes-issues/issues/830) for details.
**Expected results**:
- Design a _simple_ protocol for transferring logs. The less metadata (parsed
in log-collecting VM) the better.
- Implement log collecting service. Besides logs itself, should save
information about logs origin (VM name) and timestamp. The service should
_not_ trust sending VM in any of those.
- Implement log forwarder compatible with systemd-journald and rsyslog. A
mechanism (service/plugin) fetching logs in real time from those and sending
to log-collecting VM over qrexec service.
- Document the protocol.
- Write unit tests and integration tests.
**Knowledge prerequisite**:
- syslog
- systemd
- Python/Bash scripting
**Mentor**: [Frédéric Pierret](/team/)
### Xen GPU passthrough for Intel integrated GPUs
**Project**: Xen GPU passthrough for Intel integrated GPUs (largely independent of Qubes)
**Brief explanation**: This project is prerequisite to full GUI domain support,
where all desktop environment is running in dedicated VM, isolated from
dom0. There is already some support for GPU passthrough in Xen, but needs to be
integrated in to Qubes and probably really make working, even when using qemu
in stubdomain. GUI domain should be a HVM domain (not PV).
This should be done without compromising Qubes security features, especially:
using VT-d for protection against DMA attacks, using stubdomain for sandboxing
qemu process (if needed) - qemu running in dom0 is not acceptable. More
details in [#2618](https://github.com/QubesOS/qubes-issues/issues/2618).
**Expected results**:
- Ability to start a VM with GPU connected. VM should be able to handle video
output (both laptop internal display, and external monitors if apply). That
VM also should be able to use hardware acceleration.
- This project may require patching any/all of Xen hypervisor, Libvirt, Qemu,
Linux. In such a case, patches should be submitted to appropriate upstream
project.
- It's ok to focus on a specific, relatively new Intel-based system with Intel
integrated GPU.
**Knowledge prerequisite**:
- C language
- Kernel/hypervisor debugging
- Basics of x86_64 architecture, PCIe devices handling (DMA, MMIO, interrupts), IOMMU (aka VT-d)
- Xen hypervisor architecture
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Whonix IPv6 and nftables support
**Project**: Whonix IPv6 and nftables support
**Brief explanation**: [T509](https://phabricator.whonix.org/T509)
**Expected results**:
- Work at upstream Tor: An older version of https://trac.torproject.org/projects/tor/wiki/doc/TransparentProxy page was the origin of Whonix. Update that page for nftables / IPv6 support without mentioning Whonix. Then discuss that on the tor-talk mailing list for wider input. - https://trac.torproject.org/projects/tor/ticket/21397
- implement corridor feature request add IPv6 support / port to nftables - https://github.com/rustybird/corridor/issues/39
- port [whonix-firewall](https://github.com/Whonix/whonix-firewall) to nftables
- make connections to IPv6 Tor relays work
- make connections to IPv6 destinations work
**Knowledge prerequisite**:
- nftables
- iptables
- IPv6
**Mentor**: [Patrick Schleizer](/team/)
### Audio support for Qubes Windows Tools
**Project**: Audio support for Qubes Windows Tools
**Brief explanation**: Add audio support for Windows HVMs via Qubes Windows Tools. [#2624](https://github.com/QubesOS/qubes-issues/issues/2624)
**Expected results**: Windows HVMs should have an audio device that supports playback and recording.
**Knowledge prerequisite**: C/C++ languages, familiarity with Windows API, possibly familiarity with Windows audio stack on the driver level.
**Mentor**: [Rafał Wojdyła](/team/)
### Improve Windows GUI agent performance and stability
**Project**: Improve Windows GUI agent performance and stability
**Brief explanation**: Previous profiling has shown that the Windows GUI agent uses significant portion of VM's CPU time for mouse input simulation. This can be improved, as well as agent's stability in some cases (desktop/user switching, logon/logoff, domain-joined VMs, multiple monitors). Seamless GUI experience can be significantly improved, but that may require changes in the Qubes video driver. [#1044](https://github.com/QubesOS/qubes-issues/issues/1044) [#1045](https://github.com/QubesOS/qubes-issues/issues/1045) [#1500](https://github.com/QubesOS/qubes-issues/issues/1500) [#2138](https://github.com/QubesOS/qubes-issues/issues/2138) [#2487](https://github.com/QubesOS/qubes-issues/issues/2487) [#2589](https://github.com/QubesOS/qubes-issues/issues/2589)
**Expected results**: Reduction of agent's CPU usage, improved stability.
**Knowledge prerequisite**: C language, Familiarity with Windows API, especially the windowing stack. Familiarity with profiling and debugging tools for Windows.
**Mentor**: [Rafał Wojdyła](/team/)
### GUI agent for Windows 8/10
**Project**: GUI agent for Windows 8/10
**Brief explanation**: Add support for Windows 8+ to the Qubes GUI agent and video driver. Starting from Windows 8, Microsoft requires all video drivers to conform to the WDDM display driver model which is incompatible with the current Qubes video driver. Unfortunately the WDDM model is much more complex than the old XPDM one and officially *requires* a physical GPU device (which may be emulated). Some progress has been made to create a full WDDM driver that *doesn't* require a GPU device, but the driver isn't working correctly yet. Alternatively, WDDM model supports display-only drivers which are much simpler but don't have access to system video memory and rendering surfaces (a key feature that would simplify seamless GUI mode). [#1861](https://github.com/QubesOS/qubes-issues/issues/1861)
**Expected results**: Working display-only WDDM video driver or significant progress towards making the full WDDM driver work correctly.
**Knowledge prerequisite**: C/C++ languages, familiarity with Windows API, familiarity with the core Windows WDM driver model. Ideally familiarity with the WDDM display driver model.
**Mentor**: [Rafał Wojdyła](/team/)
### Unattended Windows installation
**Project**: Unattended Windows installation
**Brief explanation**: Simplify Windows usage by providing a tool that perform unattended installation given required input data (installation image, license key, user name, etc). Similar feature is already supported in other virtualization solutions, including VMWare Workstation and VirtualBox. [Related github issue](https://github.com/QubesOS/qubes-issues/issues/4688).
**Expected results**:
- A template for `autounattended.xml` file for Windows installer - the template should have placeholders for settings that need to be provided by the user.
- A tool for generating actual `autounattended.xml` file based on the template and user settings.
- A tool for launching Windows installation, given installation image and `autounattended.xml` file (can be the same as in the above point).
- (Optional) Unattended installation should also include Qubes Windows Tools.
- (Optional) A tool should be able to use Windows license embedded in ACPI tables - [related discussion](https://groups.google.com/d/msgid/qubes-devel/0b7fabae-f843-e7ce-40cf-193326cecdb0%40zrubi.hu)
- User documentation
- Automated tests (unit tests, integration tests)
**Knowledge prerequisite**:
- Python scripting
- Linux administration, including handling loop devices, partition tables, filesystems etc
- For optional features, C language and x86 architecture (ACPI tables)
**Mentor**: [Rafał Wojdyła](/team/), [Marek Marczykowski-Górecki](/team/)
### GNOME support in dom0 / GUI VM
**Project**: GNOME support in dom0
**Brief explanation**: Integrating GNOME into Qubes dom0. This include:
- patching window manager to add colorful borders
- removing stuff not needed in dom0 (file manager(s), indexing services etc)
- adjusting menu for easy navigation (same applications in different VMs and such problems, dom0-related entries in one place)
- More info: [#1806](https://github.com/QubesOS/qubes-issues/issues/1806)
**Expected results**:
- Review existing support for other desktop environments (KDE, Xfce4, i3, awesome).
- Patch window manager to draw colorful borders (we use only server-side
decorations), there is already very similar patch in
[Cappsule project](https://github.com/cappsule/cappsule-gui).
- Configure GNOME to not make use of dom0 user home in visible way (no search
in files there, no file manager, etc).
- Configure GNOME to not look into external devices plugged in (no auto
mounting, device notifications etc).
- Package above modifications as rpms, preferably as extra configuration files
and/or plugins than overwriting existing files. Exceptions to this rule may
apply if no other option.
- Adjust comps.xml (in installer-qubes-os repo) to define package group with
all required packages.
- Document installation procedure.
**Knowledge prerequisite**:
- GNOME architecture
- C language (patching metacity)
- Probably also javascript - for modifying GNOME shell extensions
**Mentor**: [Frédéric Pierret](/team/), [Marek Marczykowski-Górecki](/team/)
### Generalize the Qubes PDF Converter to other types of files
**Project**: Qubes Converters
**Brief explanation**: One of the pioneering ideas of Qubes is to use disposable virtual machines to convert untrustworthy files (such as documents given to journalists by unknown and potentially malicious whistleblowers) into trustworthy files. See [Joanna's blog on the Qubes PDF Convert](http://theinvisiblethings.blogspot.co.uk/2013/02/converting-untrusted-pdfs-into-trusted.html) for details of the idea. Joanna has implemented a prototype for PDF documents. The goal of this project would be to generalize beyond the simple prototype to accommodate a wide variety of file formats, including Word documents, audio files, video files, spreadsheets, and so on. The converters should prioritise safety over faithful conversion. For example the Qubes PDF converter typically leads to lower quality PDFs (e.g. cut and paste is no longer possible), because this makes the conversion process safer.
**Expected results**: We expect that in the timeframe, it will be possible to implement many converters for many file formats. However, if any unexpected difficulties arise, we would prioritise a small number of safe and high quality converters over a large number of unsafe or unuseful converters.
**Knowledge prerequisite**: Most of the coding will probably be implemented as shell scripts to interface with pre-existing converters (such as ImageMagick in the Qubes PDF converter). However, shell scripts are not safe for processing untrusted data, so any extra processing will need to be implemented in another language -- probably Python.
**Mentors**: Andrew Clausen and Jean-Philippe Ouellet
### Mitigate focus-stealing attacks
**Project**: Mitigate focus-stealing attacks
**Brief explanation**: [Focus stealing attacks](https://en.wikipedia.org/wiki/Focus_stealing) have long been an issue in Qubes OS. The Qubes community has long punted the issue due to having higher priority things to work on, and it being viewed as the responsibility of the window manager, but nevertheless it remains a serious issue, and an *effective* mitigation would be most welcome. Any student wishing to work on this would need to engage the community in a discussion about the effectiveness of their proposed solution earlier rather than later. [#1166](https://github.com/QubesOS/qubes-issues/issues/1166)
**Expected results**: Working robust focus stealing prevention for Xfce (currently the default Qubes desktop environment) or Gnome (the targeted future Qubes desktop environment).
**Knowledge prerequisite**: X APIs, Qubes GUI protocol, familiarity with the targeted window manager.
**Mentor**: Inquire on [qubes-devel][ml-devel].
### Progress towards reproducible builds
**Project**: Progress towards reproducible builds
**Brief explanation**: A long-term goal is to be able to build the entire OS and installation media in a completely bit-wise deterministic manner, but there are many baby steps to be taken along that path. See:
- "[Security challenges for the Qubes build process](/news/2016/05/30/build-security/)"
- [This mailing list post](https://groups.google.com/d/msg/qubes-devel/gq-wb9wTQV8/mdliS4P2BQAJ)
- and [reproducible-builds.org](https://reproducible-builds.org/)
for more information and qubes-specific background.
**Expected results**: Significant progress towards making the Qubes build process deterministic. This would likely involve cooperation with and hacking on several upstream build tools to eliminate sources of variability.
**Knowledge prerequisite**: qubes-builder [[1]](/doc/qubes-builder/) [[2]](/doc/qubes-builder-details/) [[3]](https://github.com/QubesOS/qubes-builder/tree/master/doc), and efficient at introspecting complex systems: comfortable with tracing and debugging tools, ability to quickly identify and locate issues within a large codebase (upstream build tools), etc.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Porting Qubes to ARM/aarch64
**Project**: Porting Qubes to ARM/aarch64
**Brief explanation**:
Qubes currently only supports the x86_64 CPU architecture. Xen currently has additional support for ARM32/ARM64 processors, however work needs to be done to integrate this into the Qubes build process, as well as work in integrating this with the Qubes toolstack and security model. This may also be beneficial in simplifying the process of porting to other architectures.
Some related discussion:
- [#4318](https://github.com/QubesOS/qubes-issues/issues/4318) on porting to ppc64.
- [#3894](https://github.com/QubesOS/qubes-issues/issues/3894) on porting to L4 microkernel.
**Expected results**:
- Add cross-compilation support to qubes-builder and related components.
- Make aarch64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- Aarch64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- Xen debugging.
- General ARM architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Porting Qubes to POWER9/PPC64
**Project**: Porting Qubes to POWER9/ppc64
**Brief explanation**:
Qubes currently supports the x86_64 CPU architecture. PowerPC is desirable for security purposes as it is the only architecture where one can get performant hardware with entirely open source firmware. Xen has **deprecated** support for Power9/PPC64 processors. Here are two directions to tackle this project from:
- Port Qubes to KVM then work on ppc64 specifics
- Implement some missing functionality in KVM then implement KVM support in the Qubes Hypervisor Abstraction Layer and build process. Improving the HAL will also be beneficial for simplifying the process of porting to further architectures and hypervisors.
- Port Xen to ppc64 then work on Qubes specifics
- For more information on porting Xen see [this thread](https://markmail.org/message/vuk7atnyqfq52epp).
More information and further links can be found in the related issue:
[#4318](https://github.com/QubesOS/qubes-issues/issues/4318).
**Expected results**:
- Add cross-compilation support to qubes-builder and related components.
- Make ppc64 specific adjustments to Qubes toolstacks/manager (including passthrough of devices from device tree to guest domains).
- ppc64 specific integration and unit tests.
- Production of generic u-boot or uefi capable image/iso for target hardware.
**Knowledge prerequisite**:
- Libvirt and Qubes toolstacks (C and python languages).
- KVM or XEN internals
- General ppc64 architecture knowledge.
**Mentor**: [Marek Marczykowski-Górecki](/team/)
### Android development in Qubes
**Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio
**Brief explanation**: The goal is to enable Android development (and testing!)
on Qubes OS. Currently it's only possible using qemu-emulated Android for ARM.
Since it's software emulation it's rather slow.
Details, reference: [#2233](https://github.com/QubesOS/qubes-issues/issues/2233)
**Expected results**:
**Knowledge prerequisite**:
**Mentor**: Inquire on [qubes-devel][ml-devel].
----
We adapted some of the language here about GSoC from the [KDE GSoC page](https://community.kde.org/GSoC).
[2017-archive]: https://summerofcode.withgoogle.com/archive/2017/organizations/5074771758809088/
[gsoc-qubes]: https://summerofcode.withgoogle.com/organizations/6239659689508864/
[gsoc]: https://summerofcode.withgoogle.com/
[team]: /team/
[gsoc-faq]: https://developers.google.com/open-source/gsoc/faq
[contributing]: /doc/contributing/#contributing-code
[patches]: /doc/source-code/#how-to-send-patches
[code-signing]: /doc/code-signing/
[ml-devel]: /support/#qubes-devel
[gsoc-participate]: https://developers.google.com/open-source/gsoc/
[gsoc-student]: https://developers.google.com/open-source/gsoc/resources/manual#student_manual
[how-to-gsoc]: http://teom.org/blog/kde/how-to-write-a-kick-ass-proposal-for-google-summer-of-code/
[gsoc-submit]: https://summerofcode.withgoogle.com/
[mailing-lists]: /support/
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
[qubes-issues-suggested]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22P%3A%20minor%22%20label%3A%22help%20wanted%22
[qubes-builder]: /doc/qubes-builder/

178
developer/general/gsod.md Normal file
View file

@ -0,0 +1,178 @@
---
layout: sidebar
title: Google Season of Docs
permalink: /gsod/
---
# 2019 Google Season of Docs
Thank you for your interest in participating in the [2019 Google Season of Docs][gsod] program with the [Qubes OS team][team]. You can read more about the Google Season of Docs in the official [guides][gsod-doc] and [FAQ][gsod-faq].
## Project Ideas List
Everyone is encouraged to add ideas to this list, either by [editing this page directly][gsod.md] (preferred) or by replying to [this thread][gsod-2019-thread] (then we'll add it to this page for you). (See our [Documentation Guidelines] for general information about how to submit changes to the documentation, and see [Help, Support, and Mailing Lists] for information about our mailing lists.)
We currently have [over a hundred open documentation issues][doc-issues] in our issue tracker. Please feel free to use these for project ideas, as appropriate.
Here's a suggested template for adding project ideas:
```
### Adding a Proposal
**Project**: Something that you're totally excited about.
**Brief explanation**: What is the project?
**Expected results**: What is the expected result in the timeframe given?
**Knowledge prerequisite**: Pre-requisites for working on the project. What knowledge or resources are needed? If applicable, links to more information or discussions.
**Mentor**: Name and email address.
```
### Offline documentation
**Project**: Offline documentation
**Brief explanation**: Qubes OS has thorough documentation on the project website, however a user may find it more convenient to view documentation - especially for troubleshooting network issues -- offline on their Qubes machine. This will improve usability for new users and better support users if they need to troubleshoot anything.
**Expected results**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1019)
- Recommend workflow and platform for displaying offline documentation
- Test workflow and platform to ensure usability and functionality
**Knowledge prerequisite**:
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
### Create guide on firstboot for new users
**Project**: Create guide on firstboot for new users
**Brief explanation**: When a user first boots Qubes after installing it, there is an opportunity to introduce the user to some of the unique functionality Qubes has. This could be the same content as the [improved getting started page](#improve-getting-started-page).
**Expected results**:
- Review [past discussions on the issue](https://github.com/QubesOS/qubes-issues/issues/1774)
- Provide visual mock-ups and proposed text
**Knowledge prerequisite**:
- some experience with Anaconda would be helpful
**Mentor**: [Marek Marczykowski-Górecki][team]
### Improve Qubes Intro page
**Project**: Improve Qubes Intro page
**Brief explanation**: The [Intro page](https://www.qubes-os.org/intro/) is the first place a prospective user goes for information about Qubes OS. It is currently text-heavy and in Question & Answer format. This project is to re-write and design the Intro page to be more appealing to prospective users.
**Expected results**:
- Review the existing page and website, similar pages for other OSes
- Provide visual mock-ups and proposed text
**Knowledge prerequisite**:
- basic Qubes OS knowledge
- [Markdown][markdown]
**Mentor**: [Michael Carbone][team]
### Improve Getting Started page
**Project**: Improve Getting Started page
**Brief explanation**: The [Getting Started page](https://www.qubes-os.org/getting-started/) is the place a new user would go to understand better how to use Qubes. It is currently has old screenshots not using the default desktop environment and could have much better flow. In addition, this improved page content may end up being served more directly to the user via the [offline documentation](#offline-documentation) or the [firstboot guide](#create-guide-on-firstboot-for-new-users).
**Expected results**:
- Review the existing page and website, similar pages for other OSes
- Provide visual mock-ups and proposed text
**Knowledge prerequisite**:
- basic Qubes OS knowledge
- [Markdown][markdown]
**Mentor**: [Michael Carbone][team]
### Improve Disposable VMs documentation
**Project**: Improve Disposable VMs documentation
**Brief explanation**: Current Disposable VMs documentation is scarce, inconsistent in places and in scattered across multiple pages, sometimes hard to find.
This project is about consolidating it into one or few easy to find pages, covering all related subjects.
And written in way easy to follow and understand, clearly separating basic use cases, advanced ones and internal details.
Additionally, terminology is used inconsistently.
**Expected results**:
- Review existing Disposable VM documentation
- Propose new documentation layout, including split between pages
- Propose updated and clarified content
**Knowledge prerequisite**:
- basic Qubes OS knowledge - [intro], [getting started]
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
### Rewrite qrexec documentation
**Project**: Rewrite qrexec documentation
**Brief explanation**: Current qrexec (qubes remote exec) documentation is hard to follow, important informations are hidden within a wall of text.
Some parts are split into multiple sections, for example version specific to avoid duplication, but it doesn't help reading it.
Additionally, protocol documentation describes only few specific use cases, instead of being clear and precise protocol specification.
Fixing this last point may require very close cooperation with developers, as the current documentation doesn't multiple corner cases (that's one of the issue with its current shape).
**Expected results**:
- Review existing [qrexec documentation](https://www.qubes-os.org/doc/qrexec3/) and an [issue about it](https://github.com/QubesOS/qubes-issues/issues/1392)
- Propose updated, consolidated admin documentation (policy writing, adding services)
- Propose consolidated protocol specification, based on the current documentation, and cooperation with developers
**Knowledge prerequisite**:
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
### Consolidate troubleshooting guides
**Project**: Consolidate troubleshooting guides
**Brief explanation**: Troubleshooting guides are scattered across many pages and sometimes incomplete, leading to repeatedly posting the same instruction over and over when helping users to diagnose problems.
This could be helped by writing consolidated guide with with a clear list of symptom-action layout.
**Expected results**:
- Review existing [troubleshooting guides](https://www.qubes-os.org/doc/#troubleshooting)
- Review [issues][doc-issues] containing common troubleshooting steps (checking specific logs etc)
- Propose updated, consolidated troubleshooting documentation, including its layout
**Knowledge prerequisite**:
- [Markdown][markdown]
**Mentor**: [Marek Marczykowski-Górecki][team]
[gsod]: https://developers.google.com/season-of-docs/
[team]: /team/
[gsod-doc]: https://developers.google.com/season-of-docs/docs/
[gsod-faq]: https://developers.google.com/season-of-docs/docs/faq
[gsod.md]: https://github.com/QubesOS/qubes-doc/blob/master/basics_dev/gsod.md
[gsod-2019-thread]: https://groups.google.com/d/msgid/qubes-project/aac9b148-4081-ebd8-cb9d-9a9191033484%40qubes-os.org
[Documentation Guidelines]: /doc/doc-guidelines/
[Help, Support, and Mailing Lists]: /support/
[intro]: /intro/
[getting started]: /getting-started/
[markdown]: https://daringfireball.net/projects/markdown/
[doc-issues]: https://github.com/QubesOS/qubes-issues/issues?q=is%3Aopen+is%3Aissue+label%3A%22C%3A+doc%22

13
developer/general/join.md Normal file
View file

@ -0,0 +1,13 @@
---
layout: sidebar
title: Join
permalink: /join/
---
Joining the Qubes OS Team
=========================
The Qubes OS Project does not currently have any open positions.
This page will be updated when open positions become available.
In the meantime, there are many different ways you can [contribute to the Qubes OS project](/doc/contributing/).

98
developer/general/package-contributions.md Normal file
View file

@ -0,0 +1,98 @@
---
layout: doc
title: Package Contributions
permalink: /doc/package-contributions/
---
Package Contributions
=====================
We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS.
This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved.
Inclusion Criteria
------------------
In order to be accepted, packages must:
* In no way weaken the security of Qubes OS.
* Be published under an open-source license (read about the [Qubes OS License]).
* Follow our [coding guidelines].
* Be thoroughly tested.
* Have a clearly-defined use case for Qubes users.
* Not be unduly burdensome to review.
(Please note that we always reserve the right to add criteria to this list.)
Contribution Procedure
----------------------
Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the [qubes-devel mailing list].
Once you have a package that's ready to become part of Qubes OS, please follow this procedure:
1. Ensure that your package satisfies the [Inclusion Criteria].
2. If your code isn't already on GitHub, create a GitHub repo that contains your code.
3. If you haven't already, [sign your code][sig].
4. Create an issue in [qubes-issues] with the title `[Contribution] your-package-name`.
Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes.
Please note that the Qubes core developers are very busy.
If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package.
If this happens, please do not be discouraged.
If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this *very* sparingly (i.e., no more than once a month).
We appreciate your understanding!
5. You may be asked followup questions.
If we decide to accept your contribution, you will be invited to join the [QubesOS-contrib] organization on GitHub as public recognition of your contribution (but without push access; see [Review Procedure]), and [QubesOS-contrib] will fork your repo.
If we decide not to accept your contribution, we will state the reason and close the issue.
Update Procedure
----------------
*Anyone* can provide an update (patch) to a contributed package, not just the person who contributed that package!
The update procedure is the same for everyone, including the original package contributor.
If you would like to update an already-contributed package (specifically, a fork owned by [QubesOS-contrib]), please submit a [signed][sig], fast-forwardable pull request to that repo with your changes.
Please note that your pull request **must** be both [signed][sig] and fast-forwardable, or else it will be closed without further review.
One or more reviewers may post comments on your pull request.
Please be prepared to read and respond to these comments.
Review Procedure
----------------
This review procedure covers both original package contributions (see [Contribution Procedure]) and all subsequent updates to those packages, including updates from the original package contributor (see [Update Procedure]).
All changes will be reviewed by a Qubes Core Reviewer (QCR) and the [Package Maintainer] (PM).
In all cases, the QCR will be a core Qubes developer.
In some cases, the QCR and the PM will be the same person.
For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.
The review procedure is as follows:
1. Someone, S, wishes to make a change to a package, P.
2. S submits a fast-forwardable pull request against the fork of P's repo owned by [QubesOS-contrib].
3. The PM reviews the pull request.
If the the pull request passes the PM's review, the PM adds a [signed][sig] *comment* on the pull request stating that it has passed review.
(In cases in which S = PM, the PM can simply add a [signed][sig] *tag* to the HEAD commit prior to submitting the pull request.)
If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request.
If the pull request passes the QCR's review, the QCR pushes a [signed][sig] tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request.
If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request.
Package Maintainers
-------------------
If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise.
As the maintainer of the package, it is your privilege and responsibility to:
* [Review][Review Procedure] each pull request made against the package.
* Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.
If you do not wish to be the maintainer of your package, please let us know.
If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.
[Inclusion Criteria]: #inclusion-criteria
[Contribution Procedure]: #contribution-procedure
[Update Procedure]: #update-procedure
[Review Procedure]: #review-procedure
[Package Maintainer]: #package-maintainers
[Qubes OS License]: /doc/license/
[sig]: /doc/code-signing/
[coding guidelines]: /doc/coding-style/
[qubes-devel mailing list]: /support/#qubes-devel
[QubesOS-contrib]: https://github.com/QubesOS-contrib
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues/

96
developer/general/style-guide.md Normal file
View file

@ -0,0 +1,96 @@
---
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 user's 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 and documentation, and they 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 | downcase}}</code>
</div>
{% endif %}
{% endfor %}
</div>
The following **colors** are currently being used on the Qubes website and documentation, and they 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 | downcase}}</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 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 %}
{% 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>

232
developer/general/usability-ux.md Normal file
View 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. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority!
We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review [our style guide](/doc/style-guide/) for other design related information.
---
## Easy To Use
An ideal user experience is friendly, and it beckons a new user to explore the interface. In this process, they can naturally discover how to use the software. Below are some guidelines that will help you design a user interface that accomplishes this goal.
<div class="focus">
<i class="fa fa-times"></i> <strong>Interfaces Should Not</strong>
</div>
- Require extensive configuration 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 the user with too much information and cognitive load
Perhaps the most common cause of mistakes is complexity. If there is a configuration setting that will significantly affect the user's 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
In making software easy to use, it is crucial to be 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."* Making sure your interfaces don't pass 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 of these are absolute maxims!
<div class="focus">
<i class="fa fa-times"></i> <strong>Avoid Acronyms</strong>
</div>
Acronyms are compact and make good names for command line tools. They do not make graphical user interfaces more intuitive for non-technical users. Until one learns an acronym's meaning, it is gibberish. Avoid acronyms in your interfaces whenever possible!
- `DVM` - Disposable Virtual Machine
- `GUID` - Global Unique Identifier
- `PID` - Process Identification Number
- `NetVM` - Networking Virtual Machine
Despite this rule, some 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 when the full words like `Universal Serial Bus` are more likely to confuse users.
<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. Sometimes, inventing a word such as `Qube` to describe a `virtual machine` makes the life of the user much easier.
- Use `Disposable Qube` instead of `DVM` or `Disposable Virtual Machine`
- Use `interface` instead of `GUI` or `Graphical User Interface`
- Use `application number` instead of `PID` or `Process Identification Number`
- Use `Networking` or `Networking Qube` instead of `NetVM` given context
---
<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 users' notification messages. Each term is very specific, but requires the user to understand virtualization to interpret.
<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`, since 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 gives better context on 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 to add words like `Domain` before items in a list or menu in an attempt to be descriptive, 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 makes extra work for the eye in parsing 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 instead as this allows the eye to easily scan the uniqueness of the items. (As per our previous example:)
~~~
Domains
- Work
- Banking
- Personal
~~~
---
## Easy To Complete
Lastly, expected (and unexpected) situations often require user actions or input. Make resolving these occurences as easy as possible to complete the action.
<div class="focus">
<i class="fa fa-times"></i><strong>Don't Leave Users Stranded</strong>
</div>
Consider the following notifications:
- `The disk space of your Qube "Work" is full`
- `There was an error saving Qube "Personal"`
Instead of displaying solvable errors like these and neglecting to provide a fix:
<div class="focus">
<i class="fa fa-check"></i><strong>Offer Actionable Solutions</strong>
</div>
Error messages and limits such as those in the previous example can be greatly improved by adding buttons or links to helpful information.
- Add a button to `Increase Disk Space`
- Add a link to a documentation page called `Troubleshoot saving data`
In adhering to these principles, you'll make undesirable situations more manageable for users instead of feeling stranded.
---
<div class="focus">
<i class="fa fa-check"></i><strong>Minimize Repetitive Steps</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 couple files in the same directory. We can alleviate some of the work by changing the process:
1. Click on `Open File` from a menu or button
2. Remember last open folder/file system
3. Select proper file
4. Complete task
Clearly, cutting out something as simple as navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item like `Open Multiple Files` might be even better, because remembering and using relevant hotkeys is often something only power users know how to do!
---
## GNOME, KDE, and Xfce
The desktop GUIs that QubesOS versions 1 - 3.1 offer are [KDE](https://www.kde.org) and [Xfce](https://xfce.org). We are currently migrating towards using [GNOME](https://www.gnome.org). We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments.
This change means you should use [GTK](https://www.gtk.org/) rather than Qt for new GUIs.
All three of these mentioned 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, 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 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