Explain new issues workflow and add triage automation

Add explanation of how to indicate the new issues workflow to MAINTAINERS.md: triage -> investigation -> devel. The different stages are indicated using Gitlab's scoped labels (mutually exclusive). These stages try to hightlight that the issue cannot be fixed and it's not moving forward because more info is needed, already. Also, add a section to CONTRIBUTING.md highlighting the importance of helping in the triage and investigation stages: developers often cannot fix bugs because lack of time to investigate, but even users that doesn't know how to fix it due to lack of knowledge of the code base can help thanks to their knowledge on networking. Finally, make the 'triage:issues' CI job to work again, adding some new policies with new automations. The automation will add or remove the labels: stale, help-needed::{triage, investigation, devel} and unassigned. The labels help-needed::* and unassigned will be automatically added to all issues without an assignee. This reflects better the reality of not having enough time to work on most of the issues unless there is some external help.
2024-06-29 06:04:26 +00:00 · 2024-05-23 11:55:52 +02:00 · 2024-05-23 11:55:52 +02:00 · cf86af6cbd
commit cf86af6cbd
parent 99f22526ec
6 changed files with 253 additions and 60 deletions
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@ -59,11 +59,11 @@ variables:
  #
  # This is done by running `ci-fairy generate-template` and possibly bumping
  # ".default_tag".
-  ALPINE_TAG:  'tag-4cf5505b3b7d'
-  CENTOS_TAG:  'tag-f78e39f6e045'
-  DEBIAN_TAG:  'tag-f7bdc50d0819'
-  FEDORA_TAG:  'tag-f78e39f6e045'
-  UBUNTU_TAG:  'tag-f7bdc50d0819'
+  ALPINE_TAG:  'tag-ec99bc32ed7f'
+  CENTOS_TAG:  'tag-a76c3f2e9d0f'
+  DEBIAN_TAG:  'tag-3f6892bcd503'
+  FEDORA_TAG:  'tag-a76c3f2e9d0f'
+  UBUNTU_TAG:  'tag-3f6892bcd503'

  ALPINE_EXEC: 'bash .gitlab-ci/alpine-install.sh'
  CENTOS_EXEC: 'bash .gitlab-ci/fedora-install.sh'
@ -628,14 +628,16 @@ pages:
  needs:
    - "t_fedora:40: [meson+gcc+docs+valgrind]"

-# triage:issues:
-#   stage: triage
-#   image: ruby:2.7
-#   script:
-#     - gem install gitlab-triage
-#     - gitlab-triage -d --token $API_TOKEN --source-id $SOURCE_ID
-#   only:
-#     - schedules
+triage:issues:
+  stage: triage
+  image: ruby:3
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULED_PIPELINE_NAME == "daily"
+  tags:
+    - placeholder-job  # The job mostly waits on network requests, so use only one CPU: https://gitlab.freedesktop.org/freedesktop/freedesktop/-/issues/1358#note_2457416
+  script:
+    - gem install gitlab-triage
+    - gitlab-triage --debug --token $API_TOKEN --source-id $CI_PROJECT_ID

 # Clean the generated images periodically to get updated snapshots of the distribution images.
 # Create an scheduled pipeline to run it, passing an AUTHFILE environment variable of type
@ -645,7 +647,7 @@ clean-images:
    - .fdo.ci-fairy
  stage: prep
  rules:
-    - if: $CI_PIPELINE_SOURCE == "schedule"
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULED_PIPELINE_NAME == "weekly"
  script:
    - ci-fairy -v --authfile $AUTHFILE delete-image --project NetworkManager/NetworkManager --all

@ -654,7 +656,7 @@ clean-images:
 workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+    - if: $CI_PIPELINE_SOURCE == 'schedule'
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH
-    - if: $CI_PIPELINE_SOURCE == 'schedule'
--- a/.gitlab-ci/ci.template
+++ b/.gitlab-ci/ci.template
@ -237,14 +237,16 @@ pages:
  needs:
    - "t_{{default_distro.name}}:{{default_distro.versions[0]}}: [meson+gcc+docs+valgrind]"

-# triage:issues:
-#   stage: triage
-#   image: ruby:2.7
-#   script:
-#     - gem install gitlab-triage
-#     - gitlab-triage -d --token $API_TOKEN --source-id $SOURCE_ID
-#   only:
-#     - schedules
+triage:issues:
+  stage: triage
+  image: ruby:3
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULED_PIPELINE_NAME == "daily"
+  tags:
+    - placeholder-job  # The job mostly waits on network requests, so use only one CPU: https://gitlab.freedesktop.org/freedesktop/freedesktop/-/issues/1358#note_2457416
+  script:
+    - gem install gitlab-triage
+    - gitlab-triage --debug --token $API_TOKEN --source-id $CI_PROJECT_ID

 # Clean the generated images periodically to get updated snapshots of the distribution images.
 # Create an scheduled pipeline to run it, passing an AUTHFILE environment variable of type
@ -254,7 +256,7 @@ clean-images:
    - .fdo.ci-fairy
  stage: prep
  rules:
-    - if: $CI_PIPELINE_SOURCE == "schedule"
+    - if: $CI_PIPELINE_SOURCE == "schedule" && $SCHEDULED_PIPELINE_NAME == "weekly"
  script:
    - ci-fairy -v --authfile $AUTHFILE delete-image --project NetworkManager/NetworkManager --all

@ -263,7 +265,7 @@ clean-images:
 workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+    - if: $CI_PIPELINE_SOURCE == 'schedule'
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH
-    - if: $CI_PIPELINE_SOURCE == 'schedule'
--- a/.triage-policies.yml
+++ b/.triage-policies.yml
@ -3,21 +3,167 @@ host_url: https://gitlab.freedesktop.org
 resource_rules:
  issues:
    rules:
+      - name: Set initial workflow stage
+        conditions:
+          state: opened
+          forbidden_labels:
+            - workflow::triage
+            - workflow::investigation
+            - workflow::devel
+        actions:
+          labels:
+            - workflow::triage
+
+      - name: Ensure that only one workflow label is used (1/2)
+        conditions:
+          state: opened
+          labels:
+            - workflow::triage
+            - workflow::investigation
+          forbidden_labels:
+            - workflow::devel
+        actions:
+          remove_labels:
+            - workflow::triage
+
+      - name: Ensure that only one workflow label is used (1/2)
+        conditions:
+          state: opened
+          labels:
+            - workflow::{triage, investigation}
+            - workflow::devel
+        actions:
+          remove_labels:
+            - workflow::triage
+            - workflow::investigation
+
+      - name: Remove help-needed::* and unassigned labels on assigned issue
+        conditions:
+          state: opened
+          ruby: resource["assignees"].length > 0
+          labels:
+            - help-needed::{triage, investigation, devel}
+            - unassigned
+        actions:
+          remove_labels:
+            - help-needed::triage
+            - help-needed::investigation
+            - help-needed::devel
+            - unassigned
+
+      - name: Add help-needed::triage and unassigned labels on unassigned issues
+        conditions:
+          state: opened
+          ruby: resource["assignees"].length == 0
+          labels:
+            - workflow::triage
+          forbidden_labels:
+            - help-needed::triage
+            - unassigned
+        actions:
+          labels:
+            - help-needed::triage
+            - unassigned
+
+      - name: Remove wrong help-needed::* labels for issues on triage stage
+        conditions:
+          state: opened
+          labels:
+            - workflow::triage
+            - help-needed::{investigation, devel}
+        actions:
+          remove_labels:
+            - help-needed::investigation
+            - help-needed::devel
+
+      - name: Add help-needed::investigation and unassigned labels on unassigned issues
+        conditions:
+          state: opened
+          ruby: resource["assignees"].length == 0
+          labels:
+            - workflow::investigation
+          forbidden_labels:
+            - help-needed::investigation
+            - unassigned
+        actions:
+          labels:
+            - help-needed::investigation
+            - unassigned
+
+      - name: Remove wrong help-needed::* labels for issues on investigation stage
+        conditions:
+          state: opened
+          labels:
+            - workflow::investigation
+            - help-needed::{triage, devel}
+        actions:
+          remove_labels:
+            - help-needed::triage
+            - help-needed::devel
+
+      - name: Add help-needed::devel and unassigned labels on unassigned issues
+        conditions:
+          state: opened
+          ruby: resource["assignees"].length == 0
+          labels:
+            - workflow::devel
+          forbidden_labels:
+            - help-needed::devel
+            - unassigned
+        actions:
+          labels:
+            - help-needed::devel
+            - unassigned
+
+      - name: Remove wrong help-needed::* labels for issues on devel stage
+        conditions:
+          state: opened
+          labels:
+            - workflow::devel
+            - help-needed::{triage, investigation}
+        actions:
+          remove_labels:
+            - help-needed::triage
+            - help-needed::investigation
+      
+      - name: Remove triage::* labels if the issue is not triaged
+        conditions:
+          state: opened
+          labels:
+            - workflow::triage
+            - triaged::{bug, RFE}
+        actions:
+          remove_labels:
+            - triaged::bug
+            - triaged::RFE
+      
+      - name: Ensure that only one triaged::* label is used
+        conditions:
+          state: opened
+          labels:
+            - triaged::bug
+            - triaged::RFE
+        actions:
+          remove_labels:
+            - triaged::RFE
+
      - name: Mark issue as stale with no activity for 4 months
        conditions:
+          state: opened
          date:
            attribute: updated_at
            condition: older_than
            interval_type: months
            interval: 4
-          state: opened
          forbidden_labels:
            - stale
        actions:
-            comment: |
-                This issue has been inactive for 4 months and got stale. Contributions welcome to move it forward.
+            comment: >-
+              This issue has been inactive for 4 months and got stale.
+              Contributions welcome to move it forward.
            labels:
-                - stale
+              - stale
+
  merge_requests:
    rules:
      - name: Mark merge-request as stale after no activity for 2 months
@ -31,7 +177,8 @@ resource_rules:
          forbidden_labels:
            - stale
        actions:
-            comment: |
-                This merge-request has been inactive for 2 months and got stale. Work is necessary to move it forward.
+            comment: >-
+              This merge-request has been inactive for 2 months and got stale.
+              Work is necessary to move it forward.
            labels:
-                - stale
+              - stale
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -33,8 +33,35 @@ and you still need to review them. You can also personally hand over the logfile
 to a NM developer to treat it confidential.


-Contribute
----------
+Help with issues triage
+-----------------------
+
+The big amount of reported issues is difficult to handle by the small team of
+developers actively working on the project. Many bugs remain unfixed because
+there is no enough time to investigate them.
+
+Working on issues triage and investigation is a very useful help that many
+people can provide very effectively, even if they can't do the fix in the
+code afterwards.
+
+This is the kind of help that may facilitate other developers to prepare a fix:
+- Investigate if it's a real bug or if it's expected behaviour.
+- Provide information and context to explain why it is a bug and what the
+  expected behaviour would be.
+- Create reproducers.
+- Investigate where the failure might be in the code, even if you don't know
+  how to fix it.
+- In a general sense, provide any information that might be useful later.
+
+Find issues with the `help-needed::triage` and `help-needed::investigation`
+label in our [issue tracker](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues)
+and help with them. Issues in "investigation" stage has been triaged, i.e.
+identified as a bug, but there is not enough information to start working on it
+yet.
+
+
+Contribute patches
+------------------

 Send patches to our repository at [gitlab.freedesktop.org](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/).
 If you are willing to contribute, please read these guidelines first:
@ -43,11 +70,8 @@ If you are willing to contribute, please read these guidelines first:

 - Work on any issue you want, but please put a comment to indicate that you are
  willing to work on it so others don't do the same work in parallel, or to
-  check whether anyone is already doing so.
-
- Issues marked as `help-wanted` are those where the NetworkManager developers
-  are explicitly asking for contributors' help, probably due to lack of capacity
-  to work on it.
+  check whether anyone is already doing so. You can find issues waiting for a
+  developer to work on it searching for the `help-needed::devel` label.

 - Issues marked as `good-first-issue` indicate that they are probably quite
  simple fixes, well suited for first time contributors.
--- a/MAINTAINERS.md
+++ b/MAINTAINERS.md
@ -6,38 +6,51 @@ Issue tracker: https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/is
 Help other maintainers with the triage following these guidelines. This way, it
 will be easier to find issues that require attention.

- Assign an issue to yourself if you are going to take care of providing the
-  required help. Assign it to another person if he/she is more suitable to help,
-  but do this quite rarely so we take care of not overloading to anyone.
+- Workflow: indicate the current stage with the corresponding label:

- Add suitable labels to indicate the state of open issues:
+  - `workflow::triage`: needs triage to determine whether is a bug, an RFE or we
+    should close it.
+
+  - `workflow::investigation`: has been triaged but more info is needed to start
+    working on a fix. This step can be skipped if enough information is provided
+    during triage.
+
+  - `workflow::devel`: on development (or waiting for it).
+
+  - Closed: the issue is already solved, either via a code fix or via providing
+    the required info. Also if the request is clearly incorrect or doesn't fit
+    at all in the project.
+
+- Assignee: assign the issue to the person that is working on it. This will
+  remove the `unassigned` and `help-needed::*` labels.
+
+- Manual labels: add suitable labels to indicate the state of open issues:

  - `need-info`: waiting for info or feedback from anyone.

+  - `good-first-issue`: the task is simple and well suited for a first time
+    contributor.
+
+  - `triaged::bug` / `triaged::RFE`: type of issue.
+
  - `need-discussion`: something is not clear about what to do, or about if
    something has to be done at all. The problem should be discussed by the
    maintainers and/or with the reporter and/or other interested parts.

-  - `triaged`: if the problem is properly explained and understood. Add also
-    one of the labels `bug` or `RFE` as corresponds.
-  
-  - `help-wanted`: request external contributors to work on this. If it's a
-    simple fix, add `good-first-issue` too.
-
-  - `work-in-progress`: anyone is already working on a Merge Request, so others.
-
  - `blocked`: the issue is waiting for something that blocks its progress

  - `close-proposed`: there are good reasons to reject the request (explain
-    those reasons when adding the label). If after a reasonable time there is no
-    additional info that is good enouch to reconsider it, the issue will be
-    closed.  
-    It is not mandatory to always use this tag before closing an issue, but
-    usually desirable.
+    those reasons when adding the label) but a chance to others to provide
+    reasons against it is desired.  
+    It is not mandatory to always use this tag.
+  
+  - `Spam`: mark as spam, blocking the author. See [damspam](https://gitlab.freedesktop.org/freedesktop/damspam/-/blob/main/README.md?ref_type=heads).

- Close an issue if the problem is already solved, either via a code fix or via
-  some information that has been provided. Also if the request is clearly
-  incorrect or doesn't fit at all in the project.
+- Automatic labels: some labels are automatically added and removed by a bot and
+  the maintainers don't need to care much about them. The label `stale` is
+  used for issues without activity for a long time. The labels `unassigned` and
+  `help-needed::{triage, investigation, devel}` are used for issues without an
+  assignee.


 Merging Merge Requests
--- a/README.md
+++ b/README.md
@ -133,7 +133,12 @@ Report bugs or feature request in our [issue tracker](https://gitlab.freedesktop
 See [Report issues](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/main/CONTRIBUTING.md?ref_type=heads#report-issues)
 for details about how to do it.

-To get involved, see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Contribute
+----------
+
+To get involved, see [CONTRIBUTING.md](CONTRIBUTING.md) to find different ways
+to contribute.


 License