{{Header}}
{{Title|title=
Bug Reports, Software Development, and Feature Requests
}}
{{#seo:
|description=How to Report (Security) Bugs in the {{project_name_long}} Operating System. The software development cycle, patches, and responsiveness to feedback and feature requests.
|image=Ladybug-156624-640.png
}} {{documentation_mininav}}
[[File:Ladybug-156624-640.png|250px|thumb]]
{{intro|
How to Report (Security) Bugs in the {{project_name_short}} Operating System. Learn about the software development cycle, patches, and our responsiveness to feedback and feature requests.
}}
= Bug Report Recommendations =
== Non-critical Bugs ==
Users who discover bugs are encouraged to report them on the [https://forums.{{project_clearnet}} {{project_name_short}} forums]. To aid developers, please adhere to the [[#Reporting_Guidelines|Reporting Guidelines]] outlined below when describing the issue.
Once the reported issues are reproduced and confirmed, our developers will discuss the problem to determine an appropriate solution or workaround. All {{project_name_short}} source code fixes and related issues are implemented as quickly as possible, and the findings are shared in the forums for public benefit.
== Security Vulnerabilities ==
* [https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure Coordinated vulnerability disclosure (CVD)]: Users are kindly asked to privately report security bugs and describe the problem in detail. Please refer to the [[#Reporting_Guidelines|Reporting Guidelines]] below for guidance. The lead {{project_name_short}} developer, Patrick Schleizer, should be contacted via OpenPGP encrypted mail before the information is published in public forums. See [[Contact|Contacting {{project_name_short}} developers]] for details. This approach ensures that vulnerabilities can be patched without endangering the {{project_name_short}} user base, and the notifier can be credited with the finding(s) once the changes are implemented in the stable repository (or in the next {{project_name_short}} release).
* Only {{project_name_short}} specific vulnerabilities: Vulnerabilities should only be reported if they are directly caused by the [https://github.com/{{project_name_short}} {{project_name_short}} source code]. Vulnerabilities in upstream projects (such as Linux, GNU, etc.) should be reported directly to those projects (upstream).
== Reporting Guidelines ==
Before developers invest time in addressing concerns, reporters should make a reasonable effort to demonstrate that it is a genuine issue.
# Ensure it is an actual bug report and not just a support request.
# [[Please_Use_Search_Engines_And_See_Documentation_First|Please Use Search Engines And See Documentation First]].
# Read [[Support]].
# Familiarize yourself with the [[Self_Support_First_Policy|Self Support First Policy]].
# [http://www.catb.org/esr/faqs/smart-questions.html How to Ask Smart Questions].
# [https://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively].
# [https://mywiki.wooledge.org/XyProblem XyProblem].
{{project_name_short}}, Qubes OS, and most other software projects expect thorough reports to include: [
This recommended format is directly taken from the [https://github.com/QubesOS/qubes-issues/issues/ Qubes OS bug tracker]; for an example, see [https://github.com/QubesOS/qubes-issues/issues/4842 this bug].
]
# The version and platform of {{project_name_short}}.
# Affected components or functionalities.
# Steps to reproduce the behavior.
# The expected behavior.
# The actual behavior, including detailed console output.
# Context: How has this issue affected you? What are you trying to accomplish? Providing context helps us determine a solution that is most useful in the real world.
# Relevant [[Documentation]] consulted.
# Any related, [https://forums.{{project_clearnet}} non-duplicate issues (bugs)].
The following example report would be considered wholly insufficient by {{project_name_short}} developers:
* Platform: {{project_name_short}} {{VersionShort}}.
* Affected functionality: System update/upgrade.
* Steps to reproduce: Update the system via terminal.
* Expected behavior: The absence of error messages.
* Actual behavior: The message "70 signatures not checked due to missing keys" is displayed.
* Context: Merely curious.
Additional details are needed to satisfy the criteria for a bug report.
== Sample Bug Report ==
In many cases only developers, developers-alike and very technical users will be able to report an actual issue based upon console output. A sample, thorough bug report is given below.
'''Table:''' ''Example {{project_name_short}} Bug Report''
{| class="wikitable"
|-
! scope="col"| '''Indicator'''
! scope="col"| '''Description'''
|-
! scope="row"| {{project_name_short}} version
| All {{project_name_short}} {{VersionShort}} variants.
|-
! scope="row"| Affected component(s) or functionality
| {{project_name_short}} firewall.
|-
! scope="row"| Steps to reproduce the behavior
|
# Enable the fail closed firewall mechanism in {{project_name_gateway_long}}. [So that networking is blocked if sdwdate.service fails to load.]
# Later on when a sdwdate package upgrade becomes available, networking is no longer functional after installation.
|-
! scope="row"| Expected behavior
| An upgrade of the sdwdate package should not break networking.
|-
! scope="row"| Actual behavior
| An upgrade of the sdwdate package breaks networking.
|-
! scope="row"| Context
| Running standard ("everyday") upgrade instructions.
|-
! scope="row"| Relevant [[Documentation]] that was consulted
| See below.
|-
! scope="row"| Any related, [https://forums.{{project_clearnet}} non-duplicate issues (bugs)]
| None, but these resources are directly relevant:
* https://github.com/{{project_name_short}}/sdwdate
|}
A detailed answer to a reported issue is more likely if:
# Reporters exert more effort, provide detailed analysis, perform multiple web searches, and read the source code beforehand; or
# The reporter is a {{project_name_short}} contributor or developer.
== Generic Bug Reproduction ==
The following concepts and principles are related:
* [[Please_Use_Search_Engines_And_See_Documentation_First|Please Use Search Engines And See Documentation First]]
* [[Unspecific]]
* [[Support]]
* [[Self_Support_First_Policy|Self Support First Policy]]
* [[Support#The_User_Co-developer_Concept|The User Co-developer Concept]]
* [[Mental Model]]
Issues unspecific to {{project_name_short}}, in short, due to the [[#Linux User Experience versus Commercial Operating Systems|organizational structure of Freedom Software]], in most cases the only realistic way to resolve questions and issues is to reduce the complexity to as few components and to research upstream (origin) resources (documentation, forums, mailing lists) and to contact upstream if applicable. For that, it is highly useful to remove the complexity of {{project_name_short}}. Rephrasing the question, removing the {{project_name_short}} specific part of it, utilizing other resources might yield more information or better help. Therefore all topics which are [[unspecific]] to {{project_name_short}} are redirected to upstream resources as per [[Self_Support_First_Policy|Self Support First Policy]].
For issues specific to {{project_name_short}} it is still highly useful to attempt to utilize the same concepts and principles as much as possible. To more colorfully explain this, an example will be used. A good example is issues with VirtualBox showing VERR_INVALID_HANDLE, {{project_name_short}} does not develop VirtualBox. {{project_name_short}} source code does not contain textual string VERR_INVALID_HANDLE. ([[Dev/git#Search_the_Source_Code|search {{project_name_short}} source code]]) The error message is generated by the VirtualBox source code and is not by the {{project_name_short}} source code. The VirtualBox community and developers have more expertise in this area.
Even if the issue is only occurring inside {{project_name_short}}, perhaps caused by {{project_name_short}} integration source code, i.e. {{project_name_short}} specific, useful things to research are:
* How is this implemented in {{project_name_short}}?
* How to reproduce this independently of {{project_name_short}}?
* How to reproduce this in Debian {{Stable project version based on Debian codename}}?
Posting a link to this wiki chapter does not imply the issue should not be discussed. On the contrary, it is an invitation according to the [[Support#The_User_Co-developer_Concept|The User Co-developer Concept]] to utilize upstream resources. If questions where asked, bug reports posted, helpful information or (partial) solution have been found, please consider editing the [[Documentation|{{project_name_short}} Documentation]] and/or providing a complete answer in the {{project_name_short}} User Forums as a contribution to {{project_name_short}}.
= Software Development Cycle =
== Community Feedback ==
The {{project_name_short}} project is highly receptive to genuine feedback and suggested improvements from users. Software projects flourish from community input and every suggestion is noted and considered.
The {{project_name_short}} community is asked to remain patient. The development cycle involves a number of competing priorities and challenges which must be overcome to achieve ambitious roadmap goals. Further, there is also an existing {{backlog}} of unresolved bugs and feature requests to address. See also [[#Policy Rationale|Policy Rationale]].
If {{project_name_short}} resources grow over time, development activity and responsiveness to user input might increase. Often, proposed improvements or fixes to the {{project_name_short}} platform are awaiting implementation due to differing developer priorities, limited human resources and/or the inordinate amount of time required to develop a particular feature or solution. In a minority of cases, the {{project_name_short}} team is unsure how to resolve a bug or implement a specific change / feature. [Some of these relate to cross-platform problems which are not {{project_name_short}}-specific.]
It is generally unhelpful to debate the priorities laid out in the future {{project_name_short}} roadmap, as this diverts energy from core development. Some major suggestions might become available in the long-term or might never eventuate. See also [[Linux User Experience versus Commercial Operating Systems]] to learn about organizational and funding issues in the Open Source ecosystem.
For some requests it might be possible to:
* get the it solved if you [[#Contributions|contribute]] and/or become a [[Contribute#Contributor|contributor]].
* have the same benefit by applying [[Self_Support_First_Policy|Self Support First Policy]].
{{Anchor|Patches are Welcome}}
== Contributions ==
Volunteer contributions to {{project_name_short}} are most welcome. All proposed patches are carefully reviewed and merged if appropriate. Volunteers with the requisite coding ability should refer to the current {{backlog}} and consult with developers before undertaking any significant body of work.
== Old Stable Support Policy ==
It is not uncommon for Linux Distributions to support multiple release versions. [
At the time of writing, Fedora supports 2 release versions - Fedora {31,32}; see https://docs.fedoraproject.org/en-US/releases/#_current_supported_releases
] The popular Debian Linux distribution [[About#Based_on_Debian|on which {{project_name_short}} is based]] not only provides the stable, testing and unstable versions, but also maintains support for the old-stable version. The main reason is because it can take a long time for some organizations to plan, test and upgrade all computers when a new stable version is released. [
https://wiki.debian.org/DebianOldStable/#FAQ
]
Supporting the old-stable version with continued security updates for a period of time provides flexibility when migrating to the stable version. However, even for distributions like Debian that have a large number of developers, it can be very difficult to support both the stable and old-stable versions. This is evident by the limited time that the old-stable version is supported after the new stable is released - currently around one year on average. [https://www.debian.org/security/faq#lifespan]
Providing extended support for previous stable versions is preferred for both large and small projects alike, but this is infeasible for {{project_name_short}} due to limited human resources. The reason is the vast majority of developer time must be focused on core components of the stable release version, otherwise providing support for both stable and old-stable would unduly stall its development. Therefore, without a significant increase in funding or manpower, the maintenance of two stable release versions is unlikely in the near or distant future.
== Package Upgrade Policy ==
Tickets that have status resolved or implemented on the {{backlog}} are not automatically pushed to the stable (or even developer) [[Project-APT-Repository|APT repository of {{project_name_short}}]]. Also referenced git commits are not intended to imply that.
* {{anchor|standard_package_migration}} Standard Package Migration ([[#standard_package_migration|link]]):
** Stable package upgrades take time in order to provide a [[Stable Version User Experience|{{project_name_short}} Stable Version User Experience]].
** Packages are uploaded to the developers repository first. After developer testing, these are migrated to the testers repository for general testing. After that, these are migrated to the stable-proposed-updates repository. Eventually, packages are migrated to the stable repository
** Standard Package Migration: package upload → developers → testers → stable-proposed-updates → stable
* {{anchor|instant_package_migration}}Instant Package Migration ([[#instant_package_migration|link]]):
** If critical security security vulnerabilities are discovered.
** Packages with very low probability of introducing system instability.
*** [[Tor Browser#Tor Browser Downloader by {{project_name_short}}|Tor Browser Downloader by {{project_name_short}}]] ([https://github.com/{{project_name_short}}/tb-updater tb-updater])
*** [https://github.com/{{project_name_short}}/binaries-freedom binaries-freedom].
** Special purpose packages such as [https://github.com/{{project_name_short}}/debug-misc debug-misc] which are not installed by default.
** Instant Package Migration: package upload → developers → all repositories (testers, stable-proposed-updates, stable)
Advanced users who do not wish to wait for package updates can of course manually apply fixes to the relevant package(s) before that time. [
For example, the {{project_name_short}} [[AppArmor]] profiles package is a prime candidate for manual fixes, as it [[AppArmor#Maintain_Tor_Browser_Functionality|frequently breaks Tor Browser functionality]] when later browser versions are released.
] Often all that is required is opening the files which were changed in a git commit(s) with root rights and emulating what the git commit would have changed. Do not copy any + or - signs that only illustrate which lines where added / removed and are not part of the actual file change. Another option is to [[Dev/Build_Documentation|update the package from source code]].
== Issue Labels ==
=== Forum Issue Tracker Labels ===
'''Table:''' ''Forum Issue Tracker Labels''
{| class="wikitable" style="background-color: #fff;text-align: center"
| '''Label Descriptor'''
| '''Description'''
|-
| open
| The issue is still in the backlog.
|-
| confirmed
| Developers or other community members were able to reproduce the issue.
|-
| diagnosed / undiagnosed
| Developers or other community members were able/unable to identify the cause of the issue.
|-
| won't fix
| This is an ambiguous label that will hopefully be avoided in future. This applies to any issue that could be theoretically fixed, but it was rejected because there was no obvious solution, it was deemed too expensive to fix (in time or resources), the fix would add too much complexity, or for other reasons. See [https://en.opensuse.org/Bug_Status_WONTFIX this entry] for a rationale.
|-
| can't fix
| Similar to the entry above.
|-
| closed
| The issue was fixed, but the solution may not have been deployed yet.
|-
| implemented
| The issue was fixed, but the solution may not necessarily have been deployed. This is distinct from the closed label because code has been devised, but it may not have yet filtered through to the {{project_name_short}} repositories (stable, stable-proposed-updates, testers or developers APT repositories).
|-
| patches welcome
| See [[Reporting_Bugs#Contributions|source code contributions]] for further information.
|-
| unsupported
| The proposed use case is [[unsupported]] and no [[contributors|contributor]] is available or volunteering to provide [[support|Free Support]] for implementation. [[Reporting_Bugs#Contributions|Contributions]] are welcome.
|-
| declined
| The feature request was [[declined]]. No contributions will be accepted.
|-
|}
= Support Request Policy =
Due to [[#Policy Rationale|constraints]],
* many support requests [[Unspecific|unspecific to {{project_name_short}}]] have to be redirected elsewhere as per the [[Self_Support_First_Policy|Self Support First Policy]],
* many features are presently [[Unsupported|either undocumented, untested, unsupported]] or [[Community Support|community support only]], and
* sometimes there are [[Declined|Declined Feature Requests]].
* {{project_name_short}} developers will normally only respond if they are convinced an actual technical, privacy or security-related problem has been identified. Many issues are unfortunately [[#Out of Scope Issues|Out of Scope Issues]].
In the past, {{project_name_short}} developers provided answers to a wide range of reported oddities, such as console output messages that were difficult for users to understand. Unfortunately this level of attention is no longer possible, for reasons outlined in this chapter. Effective December 1, 2018, the policy concerning responses to support requests and concerns had changed.
{{Anchor|Sample Non-issue}}
== Out of Scope Issues ==
For example, if a user reported that the following console message appeared during an [[Update|update]], {{project_name_short}} developers would be unlikely to respond.
70 signatures not checked due to missing keys
The reason is because developers are aware this is not symptomatic of a technical problem, but rather a minor usability issue. In case of this example, if the user reporting the problem conducted simple Internet research, they would quickly realize the cause of the error is not {{project_name_short}}-specific. [
For example, see: https://unix.stackexchange.com/questions/485349/installing-mysql-with-mysql-apt-config-missing-keys
]
As a reminder, most anomalies are generally harmless rather than [[Malware and Firmware Trojans#Valid_Compromise_Indicators_versus_Invalid_Compromise_Indicators|an indication of a compromise]]:
If trivial changes are noticed on your system -- such as a duplicate desktop icon -- this is not evidence of a hack or leak. Similarly, if warning or error messages appear that are difficult to understand, in most cases there is no need for panic. If something unexpected occurs such as the appearance of a "htaccess file in home directory", or graphical glitches emerge in some programs, then it is more likely a harmless bug and/or usability issue rather than a compromise.
Furthermore, it is in most cases unhelpful for non-technical users to run arbitrary [[Dev/certification|certification]] utilities and test websites. This is because non-technical users lack the ability to [https://www.kicksecure.com/wiki/Threat_Modeling threat model], [https://www.kicksecure.com/wiki/Mental_Model mental model], contextualize the meaning and impact of the test result let alone perform a [https://www.kicksecure.com/wiki/System_Audit system audit].
It is unlikely that arbitrary utilities or test websites used without documentation on how to interpret the results would show something spectacular, previously unknown to developers, actionable. Examples for many false-positives and minor issues can be found for [[Browser Tests]], [[Website Tests|Server / Website Tests]], [[Dev/STIG|Security Technical Implementation Guides (STIG)]] and [https://forums.whonix.org/t/run-openscap-security-test/9080 OpenSCAP security test].
== Policy Rationale ==
There are several reasons for this policy:
* Developer Time:
** Providing answers for each and every (duplicate) reported (non-)issue costs time, which could be otherwise dedicated to core development and the {{backlog}} of existing bugs.
** To get an insight of the existing developer workload, see [[What we do|selection of {{project_name_short}} project activities and maintenance tasks]] and [https://forums.kicksecure.com/c/news/ {{project_name_short}} News].
** {{Speaker_Analogy}}
** By comparison, generally the architects of complex structures like buildings or hardware (and a myriad of other professions) do not explain any technical details for free to the general public.
* Personal Initiative: {{project_name_short}} is Freedom Software ([[Reasons for Freedom Software|Why?]]), which means every aspect of the source code is available for review. This level of transparency allows those who spend enough time or monetary resources to analyze everything in detail. In the spirit of Freedom Software, {{project_name_short}} is purposefully opposed to artificial boundaries which make analysis unnecessarily more difficult.
* Feature Richness: Since {{project_name_short}} is [[About#Based_on_Debian|based on Debian]] there are thousands of software packages available for use, and not all oddities can be discussed or explained due to time constraints.
* Usability Issues: In the main, most usability issues will remain out of scope for developer attention. The reason is two-fold: either they are outside the control of the {{project_name_short}} project and/or it is not economically viable due to the very structure of Freedom Software development; see [[#Linux_User_Experience_versus_Commercial_Operating Systems|Linux User Experience versus Comparable Operating Systems]] for further information.
* Legal Liability: Due to [[Limitations on Free Speech on Website and Chat|legal liability]] and time restraints few communications can flow through {{project_name_short}} Website and {{project_name_short}} Chat.
* [[Self_Support_First_Policy#Self_Support_First_Policy_Rationale|Self Support First Policy Rationale]]
There are several reasons for this wiki entry. First, a link can be posted whenever necessary, thereby saving developers significant time and effort in addressing issues that are out of scope or non-issues. This demonstrates acknowledgement of the report, but also signals it is not cannot be processed at this time. Secondly, answering with a link is better than a non-answer. A nil response makes it unclear if the report has been seen or whether project development is even active.
Users are welcome to report whatever they like, but it is strongly recommended to first search [https://forums.kicksecure.com/search the forums] and Internet as per [[Self_Support_First_Policy|The Self Support First Policy]] to see if it was already reported - this is often the case.
It is also absolutely crucial to subscribe to and read the latest {{project_name_short}} news category 'important-news' to stay in touch with ongoing developments. This way users benefit from notifications concerning important security vulnerabilities, potential upgrade issues, common issues and improved releases which address identified issues, like those affecting the updater or other core elements. See [[Stay Tuned]]. Often issues which users are about the report are already mentioned there for example in the changelogs of release announcements.
= Issue Tracker =
== Forum Tags ==
The goal of forum tags is to maximize the usefulness of the {{project_name_short}} forums as a roadmap and issue tracker for project developers.
Previously there were no guidelines or rules on how to use discourse forum tags; anyone could create, add or change them. [
Previously it did not make sense to have a [https://forums.whonix.org/tag/testers-wanted ]testers-wanted tag] since there were around 50 requests for testing that were mostly obsolete. Therefore, forum threads listed under that forum tag were minimized to reflect up-to-date contents where testing would be useful.
Discourse forums tags can now only be changed by moderators.
Search query examples:
* [https://forums.{{project_clearnet}}/search?expanded=true&q=tags%3Astatus_open_issue_todo all status_open_issue_todo issues]
* [https://forums.{{project_clearnet}}/search?expanded=true&q=tags%3Astatus_closed_issue_implemented all status_closed_issue_implemented issues]
* [https://forums.{{project_clearnet}}/search?expanded=true&q=tags%3Acomponent_security%2Bstatus_open_issue_todo status_open_issue_todo component_security related enhancement requests (TODO)]
* [https://forums.{{project_clearnet}}/search?expanded=true&q=tags%3Acomponent_security%2Bstatus_closed_issue_implemented status_closed_issue_implemented component_security related enhancement requests (done)]
* [https://forums.{{project_clearnet}}/search?expanded=true&q=tags%3Acomponent_research%2Bstatus_open_issue_todo status_open_issue_todo component_research tasks]
* [https://forums.{{project_clearnet}}/tags list of all forum tags]
You can create a comment in a separate post such as:
* Please open.
* Please close.
* Please re-open.
* Please add tag testers-wanted.
* Please remove tag component_security.
If appropriate, the tag will be changed by a forum moderator. [
This is restricted to forum moderators because [https://meta.discourse.org/t/view-tag-changes/151679 discourse does not have a feature to view tag changes].
] Note that issue-related comments might be deleted if inappropriate, duplicated or for the sake of brevity in the discussion (like when the status update was not changed due to a mistake). Also, tags should not be appended to every discussion or question about the related subject. [
Because adding tags to everything related does not improve anything. All keywords can still be found through internal and/or external search engines.
]
If a forum thread is not tagged with the current stable release of {{project_name_short}} or the next release, then it is not on the roadmap. In this case the likelihood the issue will be resolved is lower, whether it is a feature implementation, research/task completion, or bug fix. Please refrain from debating issue priorities or the timeframe for implementation; see [[Reporting_Bugs#Community_Feedback|Community Feedback]].
= Appendix =
{{Anchor|Linux_Distributions}}
== Linux User Experience versus Commercial Operating Systems ==
{{Linux_User_Experience_versus_Commercial_Operating_Systems}}
= Footnotes =
{{reflist|close=1}}
{{Footer}}
[[Category:Documentation]]