mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-05-02 06:46:11 -04:00
Move pages on user-contributable areas to user docs
This commit is contained in:
Andrew David Wong
parent
9758d45bcc
commit
eb12a38171
4 changed files with 0 additions and 0 deletions
|
|
@ -1,78 +0,0 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Contributing to the Qubes OS Project
|
||||
permalink: /doc/contributing/
|
||||
redirect_from:
|
||||
- /en/doc/contributing/
|
||||
- /doc/ContributingHowto/
|
||||
- /wiki/ContributingHowto/
|
||||
---
|
||||
|
||||
How to Contribute to the Qubes OS Project
|
||||
=========================================
|
||||
|
||||
Thank you for your interest in contributing to Qubes! Here are some of the many
|
||||
ways in which you can help:
|
||||
|
||||
* Audit the [source code]
|
||||
* [Report security issues]
|
||||
* [Send patches][patch] to fix bugs or implement features
|
||||
* [Report bugs]
|
||||
* [Test new releases and updates]
|
||||
* Submit [HCL reports] for your hardware
|
||||
* Record [video tours]
|
||||
* Create [artwork] (plymouth themes, installer themes, wallpapers, etc.)
|
||||
* [Write and edit the documentation]
|
||||
* [Donate] to the project
|
||||
* If you represent an organization, become a [Qubes partner]
|
||||
* Answer questions on the [mailing lists]
|
||||
* Engage with us on social media:
|
||||
* Follow us on [Twitter]
|
||||
* Join us on [Reddit]
|
||||
* Like us on [Facebook]
|
||||
* Support our [StackExchange] proposal
|
||||
* And last but not least, tell your friends and colleagues about how Qubes
|
||||
can help them secure their digital lives!
|
||||
|
||||
Contributing Code
|
||||
-----------------
|
||||
|
||||
If you're interested in contributing code, the best starting point is to have a
|
||||
look at our [GitHub issues] to see which tasks are the most urgent. You can
|
||||
filter issues depending on your interest and experience. For example, here are
|
||||
some common issue labels:
|
||||
|
||||
* [Help wanted](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22&utf8=%E2%9C%93)
|
||||
* [UX and usability](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3AUX)
|
||||
* [Windows tools](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+windows+tools%22)
|
||||
* [Documentation](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+doc%22)
|
||||
* [Privacy](https://github.com/QubesOS/qubes-issues/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22privacy%22%20)
|
||||
* [Debian](https://github.com/QubesOS/qubes-issues/issues?q=is%3Aissue+is%3Aopen+label%3A%22C%3A+Debian%22)
|
||||
|
||||
Before you engage in an activity that will take you a significant amount of
|
||||
time, e.g. implementing a new feature, it's always good to contact us first,
|
||||
preferably via the [qubes-devel] mailing list. Once we've worked out the
|
||||
details, we'll add you to our [Community-Developed Feature Tracker]. We'll then
|
||||
be grateful to [receive your patch][patch].
|
||||
|
||||
|
||||
[source code]: /doc/source-code/
|
||||
[Report security issues]: /security/
|
||||
[patch]: /doc/source-code/#how-to-send-patches
|
||||
[Report bugs]: /doc/reporting-bugs/
|
||||
[Test new releases and updates]: /doc/testing/
|
||||
[HCL reports]: /doc/hcl/
|
||||
[video tours]: /video-tours/
|
||||
[artwork]: https://github.com/QubesOS/qubes-artwork
|
||||
[Write and edit the documentation]: /doc/doc-guidelines
|
||||
[mailing lists]: /mailing-lists/
|
||||
[Donate]: /donate/
|
||||
[Qubes partner]: /partners/
|
||||
[Twitter]: https://twitter.com/QubesOS
|
||||
[Reddit]: https://www.reddit.com/r/Qubes/
|
||||
[Facebook]: https://www.facebook.com/QubesOS
|
||||
[StackExchange]: https://area51.stackexchange.com/proposals/98519/qubes-os
|
||||
[GitHub issues]: https://github.com/QubesOS/qubes-issues/issues
|
||||
[qubes-devel]: /mailing-lists/#qubes-devel
|
||||
[Community-Developed Feature Tracker]: https://www.qubes-os.org/qubes-issues/
|
||||
|
||||
|
|
@ -1,182 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
Contribution Suggestions
|
||||
------------------------
|
||||
|
||||
* If you find any inaccuracies in the documentation, please correct them!
|
||||
|
||||
* If you find an inaccuracy but don't know how to correct, you can still help
|
||||
by documenting the inaccuracy. For example, if you have *thoroughly* tested
|
||||
a set of steps in the documentation and know *for certain* that they no
|
||||
longer work on a certain version of Qubes (e.g., because the steps are
|
||||
out-of-date), then please add a note to the documentation indicating this.
|
||||
You may also wish to provide a link to a relevant thread on the [mailing
|
||||
lists].
|
||||
|
||||
* Where appropriate, specify the version of the software to which your
|
||||
contribution applies. For example, if you're contributing a set of
|
||||
instructions for doing something in dom0, specify the version(s) of Qubes OS
|
||||
with which you know these instructions to work. This allows future readers to
|
||||
more easily estimate the accuracy and applicability of information.
|
||||
|
||||
|
||||
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.
|
||||
* Insert a newline at the end of each sentence.
|
||||
* Rationale: This practice 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 ###`).
|
||||
* 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/
|
||||
[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/
|
||||
[mailing lists]: /mailing-lists/
|
||||
[md]: https://daringfireball.net/projects/markdown/
|
||||
[git-commit]: /doc/coding-style/#commit-message-guidelines
|
||||
|
|
@ -1,106 +0,0 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Reporting Bugs
|
||||
permalink: /doc/reporting-bugs/
|
||||
redirect_from:
|
||||
- /en/doc/reporting-bugs/
|
||||
- /doc/BugReportingGuide/
|
||||
- /wiki/BugReportingGuide/
|
||||
- /reporting-bugs/
|
||||
- /bug/
|
||||
- /bugs/
|
||||
- /bug-report/
|
||||
- /bug-reports/
|
||||
---
|
||||
|
||||
Reporting Bugs
|
||||
==============
|
||||
|
||||
One of the most important ways in which you can [contribute to the Qubes OS
|
||||
Project] is by reporting any bugs you have found. Please note that there is a
|
||||
separate process for [reporting security issues](/security/).
|
||||
|
||||
|
||||
Before you submit a report
|
||||
--------------------------
|
||||
|
||||
Before you submit a bug report, please take a moment to check whether your issue
|
||||
has already been reported and to determine which venue is most approriate for
|
||||
it.
|
||||
|
||||
* Read the [documentation] to see whether what you've found is really a bug.
|
||||
|
||||
* Search through the existing [Qubes issues][qubes-issues] by typing your key
|
||||
words in the **Filters** box. Make 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.
|
||||
|
||||
* Search through our [mailing list] archives by visiting the Google Groups web
|
||||
interfaces for both [qubes-users] and [qubes-devel].
|
||||
|
||||
|
||||
Where to submit your report
|
||||
---------------------------
|
||||
|
||||
Our [GitHub issues][qubes-issues] tracker is not intended for personal,
|
||||
localized troubleshooting questions, such as problems that affect only a
|
||||
specific laptop model. Those questions are more likely to be answered in
|
||||
[qubes-users], which receives much more traffic. Instead, GitHub issues are
|
||||
meant to track more general bugs and enhancements that affect a broad range of
|
||||
Qubes users.
|
||||
|
||||
|
||||
How to copy information out of Dom0
|
||||
-----------------------------------
|
||||
|
||||
See [Copying from (and to) dom0](/doc/copy-from-dom0/).
|
||||
|
||||
|
||||
How to submit a report on the mailing lists
|
||||
-------------------------------------------
|
||||
|
||||
Please see the [mailing list guidelines][mailing list].
|
||||
|
||||
|
||||
How to submit a report on GitHub
|
||||
--------------------------------
|
||||
|
||||
We track all bugs in the [qubes-issues] tracker on GitHub.
|
||||
|
||||
When you file a new issue, you should be sure to include the version of Qubes
|
||||
your'e using, as well as versions of related software packages. If your issue is
|
||||
related to hardware, provide as many details as possible about the hardware,
|
||||
which could include using command-line tools such as `lspci`.
|
||||
If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [`updates-status`] repository.
|
||||
|
||||
Project maintainers really appreciate thorough explanations. It usually
|
||||
helps them address the problem more quickly, so everyone wins!
|
||||
|
||||
|
||||
Testing new releases and updates
|
||||
--------------------------------
|
||||
|
||||
Please see [Testing New Releases and Updates][testing].
|
||||
|
||||
|
||||
Improving the code
|
||||
------------------
|
||||
|
||||
Please see our guidelines on [how to contribute code].
|
||||
|
||||
|
||||
[contribute to the Qubes OS Project]: /doc/contributing/
|
||||
[documentation]: /doc/
|
||||
[qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
|
||||
[mailing list]: https://www.qubes-os.org/mailing-lists/
|
||||
[qubes-users]: https://groups.google.com/group/qubes-users
|
||||
[qubes-devel]: https://groups.google.com/group/qubes-devel
|
||||
[testing]: /doc/testing/
|
||||
[`updates-status`]: https://github.com/QubesOS/updates-status/issues
|
||||
[how to contribute code]: /doc/contributing/#contributing-code
|
||||
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Testing New Releases and Updates
|
||||
permalink: /doc/testing/
|
||||
---
|
||||
|
||||
Testing New Releases and Updates
|
||||
================================
|
||||
|
||||
Testing new Qubes OS releases and updates is one of the most helpful ways in which you can [contribute] to the Qubes OS Project.
|
||||
However, you should only attempt to do this if you know what you're doing.
|
||||
Never rely on code that is in testing for critical work!
|
||||
|
||||
Releases
|
||||
--------
|
||||
How to test upcoming Qubes OS releases:
|
||||
|
||||
* Use [qubes-builder] to build the latest release.
|
||||
* Test the latest release candidate (RC), if any is currently available.
|
||||
|
||||
See [Version Scheme] for details about release versions and schedules.
|
||||
See [Release Checklist] for details about the RC process.
|
||||
|
||||
Updates
|
||||
-------
|
||||
How to test updates:
|
||||
|
||||
* Enable [dom0 testing repositories].
|
||||
* Enable [TemplateVM testing repositories].
|
||||
|
||||
Providing Feedback
|
||||
------------------
|
||||
If you're testing new releases or updates, we would be grateful for your feedback.
|
||||
|
||||
We use an [automated build process].
|
||||
For every package that is uploaded to a testing repository, a GitHub issue is created in the [updates-status] repository for tracking purposes.
|
||||
We welcome any kind of feedback on any package in any testing repository.
|
||||
Even a simple <span class="fa fa-thumbs-up" title="Thumbs Up"></span> or <span class="fa fa-thumbs-down" title="Thumbs Down"></span> on the package's associated issue would help us to decide whether the package is ready to be migrated to a stable repository.
|
||||
If you [report a bug] in a package that is in a testing repository, please reference the appropriate issue in [updates-status].
|
||||
|
||||
[contribute]: /doc/contributing/
|
||||
[qubes-builder]: /doc/qubes-builder/
|
||||
[Version Scheme]: /doc/version-scheme/
|
||||
[Release Checklist]: /doc/releases/todo/
|
||||
[dom0 testing repositories]: /doc/software-update-dom0/#testing-repositories
|
||||
[TemplateVM testing repositories]: /doc/software-update-vm/#testing-repositories
|
||||
[automated build process]: https://github.com/QubesOS/qubes-infrastructure/blob/master/README.md
|
||||
[updates-status]: https://github.com/QubesOS/updates-status/issues
|
||||
[report a bug]: /doc/reporting-bugs/
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue