Improve gitlab issues planning

Add several clarifications and fixes to the planing after receiving
feedback.

Signed-off-by: Walter Lozano <walter.lozano@collabora.com>

content/concepts/gitlab-issues.md

@@ -21,8 +21,8 @@ plan for the migration.
 
 Nowadays Apertis uses [Phabricator] to track bugs but it is only accessible to
 users with privileges, such as maintainers or developers. One additional
-drawback is that Phabricator is an open source tool which is no longer
-supported upstream.
+drawback is that Phabricator is an open source tool which is
+[no longer supported upstream].
 
 ## Organization
 
@@ -31,13 +31,16 @@ Currently bugs are treated as Phabricator **tasks** with a bug related tag such
 only important for the management team inside Apertis, and has no value for the
 community.
 
-Bugs can also have additional tags to relate them to projects, such as
-**infrastructure**, **licensing**, releases such as **v2021** and can also have tags
-to relate them to sources, such as **test-failure**.
+Bugs can also have additional tags which allows:
+- Release: Bugs can be tagged with a release such as **v2021** or **v2022** to
+describe that the issue is present in specific releases.
+- Test-failure: This tag is used to denote bugs that are reported during the QA
+process, either from an automated test in LAVA or from a manual test.
+- Topic: Additional tags such as **infrastructure**, **licensing** can be added
+to allow easy filtering of possible connected issues.
 
-The current workflow relies mostly on the warranty/not-warranty tags
-and on the release ones (v2021, v2022pre, etc.). Other tags are not
-used on a day-to-day basis. 
+The current workflow relies mostly on the warranty/not-warranty, test-failure
+and on the release tags.
 
 ## Fields in Phabricator
 
@@ -45,25 +48,38 @@ Phabricator supports special fields that help both developers and the management
 team to keep track of the progress. The list of fields are:
 
 - Priority: Defines a priority for the issue, possible values: **highest**,
-  **high**, **normal**, **low**
+  **high**, **needs triage**, **normal**, **low**, default value **needs triage**
 - Status: Keeps track of the progress of the work, possible values:
   **unconfirmed**, **confirmed**, **in progress**, **proposed**, **submitted**,
-  **resolved**, **wont fix**
+  **resolved**, **verified**, **closed**, **wont fix**, default value **unconfirmed**
 - Visible to: Used to configure some tasks only visible to a group of people
 - Tags: Project defined tags
-- Subscribers: List of people that get a notification on changes
+- Subscribers: List of people that get a notification on changes, members of the
+management team.
 
 ## Templates in Phabricator
 
-Currently Phabricator presents a pre-formated bug template page to create a new
+Currently Phabricator presents a pre-formated [bug form] page to create a new
 bug task. This helps developers to keep a consistent format across bugs, as well as
 avoiding missing important information.
 
 ## QA Report App
 
-Apertis performs automated tests of all its images on LAVA which are launched
-on image generation. Test failures automatically generate either a new bug or
-append new entries if a previous open bug for the same test case is found.
+Quality Assurance in Apertis is managed through [QA Report App web interface]
+which summarizes the report for all the supported releases. These report are the
+result of running Apertis [test cases] on images either from an automated or
+manual test.
+
+Automated tests are run on image creation using LAVA and results are reported
+back to QA Report App. On test failures this application automatically generates
+either a new bug or append new entries if a previous open bug for the same test
+case is found.
+
+Since some test cannot be completely automated a set of them are run manually.
+The results of these tests are submitted to QA Report App in order to have
+a common source of information. In case of failure, following the same approach
+as for the automated tests, either a new bug or a new comment in an open bug
+is introduced.
 
 ## Apertimes
 
@@ -71,6 +87,71 @@ Management team inside Apertis uses **apertimes** to track progress of the
 project. This tool retrieves task information from Phabricator to generate
 reports.
 
+## Workflow with Phabricator
+
+The current workflow used for bug tracking can be described through these steps:
+
+- Bug report: A Phabricator task is created when a new bug is found, there can
+be three situations:
+  - Manual report base on user work: In some cases a user performing some kind
+  of work might notice some unexpected behavior. In this case the user is
+  encourage to create a new bug using the [bug form].
+  - Manual report based on test suite: Apertis provides a [test suite] for its
+  releases, some of which need to be run manually. When the QA process is run a
+  failure is reported through the [bug form].
+  - Automatic report based on LAVA jobs: As mentioned the [test suite] includes
+  automated tests that are run on LAVA. [QA Report App] automatically creates
+  a bug on failures.
+
+On bug reporting it is important to try to include as much accurate
+information as possible. In this regard, a proper title, description and tags
+can help on later steps.
+
+- Bug triage: On weekly basis the list of bugs is checked and new bugs are
+trigaged with a priority as mentioned in [Fields in Phabricator]. Additionally,
+during this process for bugs with **highest** or **high** priority that require
+urgent attention, a developer is assigned. In other cases, developers claim a bug
+based on the priorities and their skills. Additionally, tags can be added to
+make it easier to connect related bugs and to help the management team to
+keep track of the task in progress.
+
+- Once a developer starts to work on a bug they change the **status** to
+**in progress** and updates the task regularly with the progress.
+
+- After debugging, a solution is designed and proposed, usually by submitting a
+Draft [Merge Request] to discuss the approach. When doing this **status** is
+updated to **proposed**, to show that there is a proposed possible fix for the
+issue.
+
+- During the review process different things can happen
+  - The proposed solution is accepted by a developer with experience in the field
+  in which case it can be merged. This is usually the case for small fixes.
+  - The proposed solution is accepted but additional work needs to be done to
+  fix the issue. This goes from additional work on the MR or a new MR with
+  additional changes. In this case when additional MR are submitted the
+  **status** can be changed to **submitted**.
+  - In some cases the root cause of the problem is in an upstream issue, from
+  which information or feedback is required. Under such circumstances, the
+  **status** can be updated to show that the developer is waiting for upstream
+  by setting it as **upstream**.
+
+- When all the MR are merged and no additional work needs to be done the
+**status** should be updated to **resolved**.
+
+- Finally, the reporter can check if the issue is solved in which case the
+**status** should be changed to **verified**. If the reporter has doubts about
+the issue, he can request additional information and set the **status** to
+**need info**.
+
+- In some cases, after investigating a bug, evaluate its impact and the possible
+solutions the best action is not to fix it. A good example of this case are
+packages no longer supported. In order to make this clear the **status** should
+be updated to **wont fix**.
+
+During all the steps described any developer can add comments to help to fix the
+issue. It is also possible that members of the management team queries the
+the status of the bugs.
+
 # Proposal
 
 As previously mentioned, given all the Apertis related projects are already hosted
@@ -91,15 +172,18 @@ which will also help the management team, since there will be a new different is
 for every new issue. This is the same approach Debian uses in its [bug tracking system].
 
 This approach has also the advantage of making transition from Phabricator easier
-as issues will be imported to only one project.
+as issues will be migrated to only one project.
 
-During the import open bugs in Phabricator will be added to Gitlab with title, description, priority,
+During the migration open bugs in Phabricator will be added to Gitlab with title, description, priority,
 status and tags set. In the description, a link to the Phabricator task will be added
 to more easily check the history. Importing the history is not recommended since there
 could be sensitive data, additionally comments also wouldn't have a correct datetime set.
 For closed bugs, since there is no value on importing them without the history the
 recommendation is to keep them only in Phabricator.
 
+After the import, which is one time operation, Gitlab issues will be the main
+repository for open or new bugs.
+
 The use of tags in Phabricator can be emulated in Gitlab with labels, making the
 transition almost transparent for end users.
 
@@ -126,11 +210,14 @@ supports the use of [confidential issues] which has visibility set to only team
 Tags can be easily implemented by labels since they have the same behavior,
 providing a very flexible way of connecting issues.
 
-Finally, subscribers can be handled using the notification system of Gitlab.
+Finally, subscribers can be handled using the [Gitlab notifications].
 [Issues templates](#templates-in-gitlab) can be configured to notify people about
 new activity by sending an email allowing all team members to be informed.
 Gitlab supports different [notification levels] providing a way for users to
-configure them according to their needs.
+configure them according to their needs. Since the templace will issue a
+mention to a default list of subscribers, everyone in that list who have not
+disabled notification will receive an e-mail on bug report and in subsequent
+comments.
 
 ## Templates in Gitlab
 
@@ -174,8 +261,8 @@ The easiest way to implement this is to keep private information in Phabricator
 as it is the tool currently used, reducing the complexity of the solution. With
 this approach bugs will be handled on Gitlab issues but a Phabricator task will
 be created and linked to track private management information. To make this
-possible a tool should be created to create a Phabricator task based on a Gitlab
-issue with the same title and a description referencing it. The management team
+possible a tool should be developed to create a Phabricator task based on a Gitlab
+issue with the same title and a description, including a link, referencing it. The management team
 will use this task to track only private data. Lastly, since management data will
 remain available in Phabricator, **apertimes** tool doesn't require any update,
 making the transition easier.
@@ -187,6 +274,14 @@ by priority, which should help tracking the most important issues. It is also po
 to create multiple issue boards per project, to highlight other aspects, such as
 **bug-type**.
 
+## Workflow
+
+The current workflow will suffer only minimal changes after switching to Gitlab
+issues. All the steps described in [Workflow with Phabricator] can be followed
+using Gitlab issues, however, with the new approach task will be automatically
+created and linked to Phabricator to allow the management team to hold private
+data.
+
 # Summary
 
 The table below shows a summary for the mapping between Phabricator and Gitlab
@@ -232,31 +327,53 @@ Gitlab issues, and another to [Export/import] Phabricator tasks into Gitlab issu
 For the actual migration, first a clean up of the current open bugs list should be performed,
 to avoid importing useless information. After this point, a freeze period should
 be started to guarantee that no modification to the bugs is made on Phabricator during the migration.
-In this context the export/import operation can be triggered, which should end
+This freeze period will be divided in two, a hard freeze and a soft one.
+
+During the hard freeze the export/import operation will be triggered, which will end
 with a production test to confirm that all bugs have been migrated and tools
-work as expected. The freeze period should be minimal, a first estimation is a few
-days, which should be enough to run tests and fix trivial problems.
+work as expected. The main purpose of this tests is to spot any blocker for considering
+Gitlab issues as the main bug repository. For any no-blocker issue a task will be
+created. The estimation for this hard freeze period is one day.
+
+During the soft freeze period, adding bugs will be enabled only with strict control
+for just a few people to allow further tests to be run and to fix minor issues.
+The estimation for this soft freeze period is 3 days. In case that no issues are
+found the soft freeze period will be reduced.
+
+If during the hard freeze period a blocker issue is found which will be unable to
+fix during the hard freeze, the migration will be aborted and a new migration
+schedule will be planned.
 
 # Steps
 
 - Create test environment on Gitlab
-- Enhance QA Report App to use Gitlab issues instead of Phabricator
-- Enhance Apertimes to use Gitlab issues instead of Phabricator
+- Enhance QA Report App to report failure to Gitlab issues instead of Phabricator
 - Create script to export bugs
 - Cleanup bug list
-- Freeze bug report/update on Phabricator
+- Hard freeze bug report/update on Phabricator
 - Export bug list
 - Import bugs list
 - Perform production test
+- Soft freeze bug report/update on Gitlab
+- Additional tests and controlled bug report
 - Unfreeze bug report/update on Gitlab
 
 [boards]: https://docs.gitlab.com/ee/user/project/issue_board.html
-[bug tracking system]: bugs.debian.org
+[bug form]: https://phabricator.apertis.org/maniphest/task/edit/form/8/
+[bug tracking system]: https://bugs.debian.org
 [confidential issues]: https://docs.gitlab.com/ee/user/project/issues/confidential_issues.html
+[Fields in Phabricator]: #fields-in-phabricator
+[Gitlab notifications]: https://docs.gitlab.com/ee/user/profile/notifications.html
 [import from csv]: https://docs.gitlab.com/ee/user/project/issues/csv_import.html
 [import from Phabricator]: https://docs.gitlab.com/ee/user/project/import/phabricator.html
 [labels]: https://docs.gitlab.com/ee/user/project/labels.html
+[no longer supported upstream]: https://www.phacility.com/phabricator/
 [notification level]: https://docs.gitlab.com/ee/user/profile/notifications.html#notification-levels
 [permissions]: https://docs.gitlab.com/ee/user/permissions.html
-[Phabricator]: www.phabricator.apertis.org
+[Phabricator]: https://www.phabricator.apertis.org
+[QA Report App]: #qa-report-app
+[QA Report App web interface]: https://lavaphabbridge.apertis.org/
 [templates]: https://docs.gitlab.com/ee/user/project/description_templates.html
+[test cases]: https://qa.apertis.org/
+[Merge Request]: https://gitlab.apertis.org/dashboard/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&assignee_id=None
+[Workflow with Phabricator] #workflow-with-phabricator