From 9b3b486d232cfb65c7801314185db9258ac7b4fb Mon Sep 17 00:00:00 2001
From: Marta Rybczynska <marta.rybczynska@huawei.com>
Date: Wed, 30 Jun 2021 07:43:29 +0200
Subject: [PATCH] contributing/bug_policy.rst: Add the bug policy

The bug policy describes how we deal with bugs: get reports, set
their priority, classify them, then fix them and release and update.

Signed-off-by: Marta Rybczynska <marta.rybczynska@huawei.com>
---
 contributing/bug_policy.rst | 167 ++++++++++++++++++++++++++++++++++++
 contributing/index.rst      |   1 +
 2 files changed, 168 insertions(+)
 create mode 100644 contributing/bug_policy.rst

diff --git a/contributing/bug_policy.rst b/contributing/bug_policy.rst
new file mode 100644
index 0000000..a81f2c0
--- /dev/null
+++ b/contributing/bug_policy.rst
@@ -0,0 +1,167 @@
+.. SPDX-FileCopyrightText: Huawei Inc.
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
+.. include:: ../definitions.rst
+
+Bug handling process
+####################
+
+Overview
+********
+
+|main_project_name| is aiming to build a secure system from the foundation,
+applying the best industry practices in terms of development quality. However,
+as in every software projects, bugs do happen. This process explains how we
+handle bugs.
+
+How to report a bug?
+********************
+
+If you think you have found a bug in our distribution, please file a bug report
+in our bug tracker and in the project that you think is the source of the
+issue. Use the provided template:
+
+* The module affected
+* What is the action and the result you see? (the bug)
+* What is the action and the result you expect? (the correct behaviour)
+* Frequency: always, sometimes, one-time issue
+* Tested version (image name and version, platform)
+* Do you know any workaround of this issue?
+* Do you have a fix for this issue?
+
+Developers review the reported issues and perform triage (see below). When a fix
+is available, the ticket is updated with the details of the solution.
+
+Which modules do we support?
+****************************
+
+We do support all layers included in our reference images and blueprints. It means
+we accept bug reports in those layers. If the issue affects the upstream part of
+the layer, we are going to redirect the report to the upstream project and work
+with upstream on a solution.
+
+Bug triage
+**********
+
+The bug triage is a process where developers asses the bug and set its
+severity and domain. At the end of this process the bug will:
+
+* Be classified as a security issue, normal bug, feature request, or be rejected
+  if the feature is working as planned or could not be reproduced.
+* Have its severity set. Please refer to the documentation of severity levels
+  below.
+* Have its domain set. The domains include categories like: toolchain, kernel,
+  Over-the-Air Update (OTA); they can change over time. The bug tracker will
+  include the latest list.
+
+If the bug is classified as a security vulnerability, the engineer assesing
+the issue will create a new ticket in the private security bug tracker and the
+discussion will continue in the security bug tracker from that point.
+Please refer to the CVE Process for details.
+
+If the bug is confirmed as a bug, the developer will assign bug severity:
+critical, normal, minor or low.
+
+.. note::
+
+    *Critical* severity bugs make a feature unusable, cause a major data loss or
+    hardware breakage. There is no workaround, or a complex one.
+    *Normal* severity bugs make a feature hard to use, but there is a workaround
+    (including another feature to use instead of the desired one).
+    *Minor* severity bugs cause a loss of non-critical feature (like missing or
+    incorrect logging).
+    *Low* severity bugs cause minor inconveniences (like a typo in the user
+    interface or in the documentation).
+
+The bug can originate in a package developed by the project, or from one we use
+from an upstream source. The process of handling a bug report will change
+between those two cases:
+
+When the issue is in the code developed by the project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the case where the bug originates in the code directly maintained by the
+Project, the bug is handled directly in the bug tracker.
+
+When the issue originates from upstream code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the issue was identified in upstream code, we report an upstream issue in
+a way appropriate to the upstream project. We store the reference to the upstream
+bug report in our bug tracker. Depending on the bug severity,
+we might decide to develop and maintain a fix locally. However, we strongly
+prefer to upstream the fix first, and then get it with a regular upstream code
+update.
+
+Please note also that we periodically update maintained packages from upstream
+sources, regardless of the bugs filled in our system. Our goal is to update to
+the latest stable version of the package.
+
+Detailed workflow
+*****************
+
+Bug sources
+^^^^^^^^^^^
+
+Bugs might be reported by different sources, including Project's own findings
+(like QA), partner findings, community, or security researchers. There might be
+also different ways the Project team learns about the issue, including
+Mattermost channels, discussion forums etc. Issues coming from different sources
+are centralized in the bug tracker, which also provides an unified
+identification of all issues.
+
+Acknowledgement and bug triage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After the bug is entered, a developer will perform triage. The process starts
+from acknowledging the issue and then consists of verifying all the information
+provided by the bug reporter to reproduce the issue. The developer performing
+triage might ask additional questions. Then they assign severity and domain to
+the issue in the bug tracker. They also check which versions are affected and might
+modify the severity level set by the reporter.
+Any project member, or the bug reporter, who disagrees with the assignment might
+comment on the issue.
+
+If there is a fix available from the reporter, the developer also verifies if
+the fix is correct and matches the IP policy. If the fix is judged acceptable,
+the process might skip to the Releasing step.
+
+We aim at the first answer of the triage (either finishing triage, or additional
+questions to the reporter) in three working days for critical bugs and seven days
+for other bugs. In case of a critical bug, the person performing triage informs
+the maintainers of the affected subsystem.
+
+Prioritizing and fixing
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Bugs with the severity attached enter the prioritization process. It includes a weekly
+meeting when the team reviews bugs entered or modified during the last week: those
+during the process of triage, and those with the triage finished. For the bugs with
+triage finished, the team sets the priority and might assign it to a developer.
+
+The bug fixes should follow the same contributions guidelines as any other
+contribution. The best practice is to develop a fix for the bug in a separate
+branch. Fixes for related bugs are possible in the same branch.
+
+Releasing
+^^^^^^^^^
+
+When a bug fix is available in a branch, the developer creates a merge request.
+When the change is accepted, it is merged in the main branch. The developer in
+charge of the bug verifies with the release manager to which branches the change
+should be backported.
+
+If the bug comes from an upstream project, developers upstream the bug fix. If
+the upstream is delayed, the Project might ship a local fix. However, we aim at
+upstreaming all fixes.
+
+During the time of development of the patch and eventual upstream, the developer
+updates the documentation (if appropriate), and adds a notification to the release
+notes. Our release notes contain: links to bugs fixed in the release, links to CVEs
+fixed in the release (publicly known) and a list of CVEs fixed that are still under
+embargo.
+
+If the bug is classified as critical, it might be decided to perform a separate
+bugfix release to fix the issue. Otherwise, the bug fix lands in the next bugfix
+release.
diff --git a/contributing/index.rst b/contributing/index.rst
index 42a6aee..a9f87c8 100644
--- a/contributing/index.rst
+++ b/contributing/index.rst
@@ -20,3 +20,4 @@ requirements.
    reuse
    dco
    devtool
+   bug_policy
-- 
GitLab