1. About

The Qubes Community Collaboration is an independent project run by volunteers striving to build and improve end-user content for Qubes OS, such as guides, documentation, code & scripts, tips, …

The project’s goals are:

Disclaimer: this site is run by volunteers. The Qubes OS Project is not affiliated with this site and does not endorse the content of any of these pages. The members of this community are Qubes users so they obviously focus on security but there’s no guarantee about the content published in this site so use it at your own risk.

2. Content

The docs/ and code/ subfolders in the ‘Contents’ repository contain contributed documentation that has been reviewed, and code + links to third-party resources.

Ongoing reviews and QA of pending user-contributed content can be seen in issues and pull requests (see section Contributing below).

Documentation suggestions are filed as issues with a Doc suggestion: ... title. Their purpose is:

3. Contributing

Anyone is welcome to submit content or documentation suggestions they deem fit for inclusion in this community effort (or potentially in the official Qubes documentation). As Qubes OS users we value privacy and security so please keep the project’s collective vision in mind.

Contributing content is done:

Documentation suggestions are filed as new issues with a Doc suggestion: title (eg. Doc suggestion: listing disk usage in R4). A quick description of the suggestion should be given in the issue’s body, with links to relevant mailing list posts or third-party resources if applicable. It isn’t mandatory that the user who filed the issue write the documentation: anyone can pick up an issue and submit documentation.

The ‘Contents’ repository is where most pull requests and issues are expected to be submitted. Contributors who plan to submit content to the official qubes-doc repository but who would like to get preliminary feedback/QA from the community can submit pull requests to the forked qubes-doc repository.

Credit/authorship: when contributing original documentation or significantly improving pages, you may add your github ID to a Contributor(s): xxx line at the end of the document. Note that every contribution is kept in git’s log/history anyway but a file’s history isn’t visible in github’s web UI when the file has been moved or renamed.

4. Licensing

GPLv2 or later is required for any documentation content so that it matches QubesOS’s official documentation. You are otherwise free to use whatever license you want when submitting code/programs, provided it fits in the open source git/fork model. Note that GPLv2 will be assumed if content is published without mentioning its license.

5. Learning git for further contributions

It would ease the burden on community members if returning contributors who are not proficient with git learn the few basic concepts required to submit pull requests themselves.

This github help page explains what pull requests are.

The official Qubes OS documentation contribution guidelines is then a good place to start with. It is based on contributing to the official qubes-doc repository but is applicable to this (or any other) project.

However the guide doesn’t approach the problem of keeping a forked repository synchronized with “upstream” (eg. the official repository). This isn’t a trivial problem (github help page), especially when you have made changes in your forked repository (stackoverflow post). So until you are proficient enough to understand the steps involved, a simple alternative that does not require command line usage is to delete the forked repository and re-fork it from upstream. This is a bit of a “nuclear” option though and you’ll obviously lose any changes you’ve made in your forked repository.