Split actions into reusable steps (fixes #213, fixes #77, embeds #233, #236, #253) (#232)

* Extract create and update issue

* Remove client as action attributes

* Remove useless code

* Extract add comment

* Remove indirection with comments for changes

* Instantiate context in __call__ instead of each method

* Remove usage of self in _update_issue()

* Split default with status and assignee into smaller bits

* Rename create_comment()

* Remove class inheritance between default and default with status and assignee (ref #77) (#233)

* Move helpers to jbi.services.jira and bugzilla

* Move bugzilla out of jira module

* Add type annotations

* Update code comment about bug.comment

* Chain operations instead of using nested conditions (with `:=` operators) (#236)

* Rename ActionLogContext to ActionContext

* Rename log_context to context

* Remove := operator and chain operations

* Remove the maybe_ from services.jira

* Align signatures of action functions

* Do not duplicate parameters between init and call

* Runner now instantiates context

* Pass actions contexts to action tests

* Update actions docs

* Remove redundant parameters

* Adjust parameters between default.py and jira.py

* Inherit JiraContext from Context

* Remove useless and confusing condition

* Replace repetitive calls with list of steps

* Let the runner set the ActionContext operation

* Reintroduce maybe_ for optional steps

* Load default action steps from configuration (#253)

* Move steps to jbi.actions.steps

* Rename test_default to test_steps

* Move test_default_with_assignee_and_status into test_steps

* Load default action steps from configuration

* Add tests for the default action behaviour

* Rename groups of steps. create -> new, update -> existing

* Remove default value config/config.prod.yaml

Co-authored-by: bsieber-mozilla <[email protected]>

* Move remapping of steps into helper

* Remove useless pylint annotation

* Adjust docstrings

* Merge unspecified groups with default ones

* Update secrets baseline

Co-authored-by: bsieber-mozilla <[email protected]>

Co-authored-by: bsieber-mozilla <[email protected]>

Co-authored-by: bsieber-mozilla <[email protected]>

Author: leplatrem

.secrets.baseline

@@ -122,9 +122,9 @@
         "filename": "README.md",
         "hashed_secret": "04e78d6e804f2b59e6cb282cb9ed2c7bfd8a9737",
         "is_verified": false,
-        "line_number": 218
+        "line_number": 242
       }
     ]
   },
-  "generated_at": "2022-08-30T10:02:55Z"
+  "generated_at": "2022-09-28T11:04:17Z"
 }

README.md

@@ -66,56 +66,24 @@ A bit more about the different fields...
 ## Available Actions
 
 ### Default
-The `jbi.actions.default` action will create or update the Jira issue and its comments.
-It will also set the Jira issue URL in the Bugzilla bug `see_also` field.
+The `jbi.actions.default` action will take the list of steps to be executed when
+the Webhook is received from configuration.
+When none is specified, it will create or update the Jira issue, publish comments when
+assignee, status, or resolution are changed, or when a comment is posted on the Bugzilla ticket.
 
-**Parameters**
-
-- `jira_project_key`
-    - string
-    - The Jira project identifier
-- `sync_whiteboard_labels`
-    - boolean
-    - Whether to sync the Bugzilla status whiteboard labels to Jira. Defaults to `true`.
-
-Example configuration:
-```yaml
-    whiteboard_tag: example
-    contact: [email protected]
-    description: example configuration
-    module: jbi.actions.default
-    parameters:
-      jira_project_key: EXMPL
-```
-
-Example configuration that disables setting labels in Jira:
-```yaml
-    whiteboard_tag: example
-    contact: [email protected]
-    description: example configuration
-    module: jbi.actions.default
-    parameters:
-      jira_project_key: EXMPL
-      sync_whiteboard_labels: false
-```
-
-### Default with assignee and status action
-The `jbi.actions.default_with_assignee_and_status` action adds some additional
-features on top of the default.
-
-It will attempt to assign the Jira issue the same person as the bug is assigned to. This relies on
-the user using the same email address in both Bugzilla and Jira. If the user does not exist in Jira
-then the assignee is cleared from the Jira issue. The Jira account that JBI uses requires the "Browse
-users and groups" global permission in order to set the assignee.
-
-If configured, the action supports setting the Jira issues's status when the Bugzilla status and resolution change.
+It will also set the Jira issue URL in the Bugzilla bug `see_also` field, and add a link
+to the Bugzilla ticket on the Jira issue.
 
 **Parameters**
 
 - `jira_project_key`
     - string
     - The Jira project identifier
-- `sync_whiteboard_labels`
+- `steps`
+    - mapping [str, list[str]]
+    - If defined, the specified steps are executed. The group of steps listed under `new` are executed when a Bugzilla event occurs on a ticket that is unknown to Jira. The steps under `existing`, when the Bugzilla ticket is already linked to a Jira issue. The steps under `comment` when a comment is posted on a linked Bugzilla ticket.
+    If one of these groups is not specified, the default steps will be used.
+- `sync_whiteboard_labels` (optional)
     - boolean
     - Whether to sync the Bugzilla status whiteboard labels to Jira. Defaults to `true`.
 - `status_map` (optional)
@@ -125,32 +93,88 @@ If configured, the action supports setting the Jira issues's status when the Bug
     - mapping [str, str]
     - If defined, map the Bugzilla bug resolution to Jira issue resolution
 
-Example configuration:
+Minimal configuration:
 ```yaml
     whiteboard_tag: example
     contact: [email protected]
-    description: example configuration
-    enabled: true
-    module: jbi.actions.default_with_assignee_and_status
+    description: minimal configuration
     parameters:
       jira_project_key: EXMPL
-      status_map:
-        NEW: "In Progress"
-        FIXED: "Closed"
-      resolution_map:
-        FIXED: "Done"
-        DUPLICATE: "Duplicate"
-        WONTFIX: "Won't Do"
+```
+
+Full configuration, that will set assignee, change the Jira issue status and resolution.
+
+```yaml
+- whiteboard_tag: fidefe
+  contact: [email protected]
+  description: full configuration
+  enabled: true
+  module: jbi.actions.default
+  parameters:
+    jira_project_key: FIDEFE
+    steps:
+      new:
+      - create_issue
+      - maybe_delete_duplicate
+      - add_link_to_bugzilla
+      - add_link_to_jira
+      - maybe_assign_jira_user
+      - maybe_update_issue_resolution
+      - maybe_update_issue_status
+      existing:
+      - update_issue
+      - add_jira_comments_for_changes
+      - maybe_assign_jira_user
+      - maybe_update_issue_resolution
+      - maybe_update_issue_status
+      comment:
+      - create_comment
+    status_map:
+      ASSIGNED: In Progress
+      FIXED: Closed
+      WONTFIX: Closed
+      DUPLICATE: Closed
+      INVALID: Closed
+      INCOMPLETE: Closed
+      WORKSFORME: Closed
+      REOPENED: In Progress
+    resolution_map:
+      FIXED: Done
+      DUPLICATE: Duplicate
+      WONTFIX: "Won't Do"
 ```
 
 In this case if the bug changes to the NEW status the action will attempt to set the linked Jira
 issue status to "In Progress". If the bug changes to RESOLVED FIXED it will attempt to set the
 linked Jira issue status to "Closed". If the bug changes to a status not listed in `status_map` then
 no change will be made to the Jira issue.
+### Available Steps
+
+- `create_issue`
+- `maybe_delete_duplicate`
+- `add_link_to_bugzilla`
+- `add_link_to_jira`
+- `maybe_assign_jira_user`:
+  It will attempt to assign the Jira issue the same person as the bug is assigned to. This relies on
+  the user using the same email address in both Bugzilla and Jira. If the user does not exist in Jira
+  then the assignee is cleared from the Jira issue. The Jira account that JBI uses requires the "Browse
+  users and groups" global permission in order to set the assignee.
+- `maybe_update_issue_resolution`:
+  If the Bugzilla ticket resolution field is specified in the `resolution_map` parameter, it will set the
+  Jira issue resolution.
+- `maybe_update_issue_status`:
+  If the Bugzilla ticket status field is specified in the `status_map` parameter, it will set the
+  Jira issue status.
+- `update_issue`
+- `add_jira_comments_for_changes`
+- `maybe_assign_jira_user`
+- `maybe_update_issue_resolution`
+- `maybe_update_issue_status`
+- `create_comment`
 
 ### Custom Actions
-If you're looking for a unique capability for your team's data flow, you can add your own Python methods and functionality[...read more here.](jbi/actions/README.md)
 
+If you're looking for a unique capability for your team's data flow, you can add your own Python methods and functionality[...read more here.](jbi/actions/README.md)
 
 ## Diagram Overview
 

config/config.nonprod.yaml

@@ -12,9 +12,22 @@
   contact: [email protected]
   description: Flowstate whiteboard tag
   enabled: true
-  module: jbi.actions.default_with_assignee_and_status
   parameters:
     jira_project_key: MR2
+    steps:
+      new:
+        - create_issue
+        - maybe_delete_duplicate
+        - add_link_to_bugzilla
+        - add_link_to_jira
+        - maybe_assign_jira_user
+        - maybe_update_issue_resolution
+        - maybe_update_issue_status
+      existing:
+        - update_issue
+        - maybe_assign_jira_user
+        - maybe_update_issue_resolution
+        - maybe_update_issue_status
     status_map:
       ASSIGNED: In Progress
       FIXED: In Review

config/config.prod.yaml

@@ -19,9 +19,22 @@
   contact: [email protected]
   description: Firefox Front End whiteboard tag
   enabled: true
-  module: jbi.actions.default_with_assignee_and_status
   parameters:
     jira_project_key: FIDEFE
+    steps:
+      new:
+        - create_issue
+        - maybe_delete_duplicate
+        - add_link_to_bugzilla
+        - add_link_to_jira
+        - maybe_assign_jira_user
+        - maybe_update_issue_resolution
+        - maybe_update_issue_status
+      existing:
+        - update_issue
+        - maybe_assign_jira_user
+        - maybe_update_issue_resolution
+        - maybe_update_issue_status
     status_map:
       ASSIGNED: In Progress
       FIXED: Closed
@@ -40,9 +53,22 @@
   contact: [email protected]
   description: Flowstate whiteboard tag
   enabled: true
-  module: jbi.actions.default_with_assignee_and_status
   parameters:
     jira_project_key: MR2
+    steps:
+      new:
+        - create_issue
+        - maybe_delete_duplicate
+        - add_link_to_bugzilla
+        - add_link_to_jira
+        - maybe_assign_jira_user
+        - maybe_update_issue_resolution
+        - maybe_update_issue_status
+      existing:
+        - update_issue,
+        - maybe_assign_jira_user
+        - maybe_update_issue_resolution
+        - maybe_update_issue_status
     sync_whiteboard_labels: false
     status_map:
       ASSIGNED: In Progress

jbi/actions/README.md

@@ -12,13 +12,13 @@ Let's create a `new_action`!
 
    ```python
    from jbi import ActionResult, Operation
-   from jbi.models import BugzillaBug, BugzillaWebhookEvent
+   from jbi.models import ActionContext
 
    JIRA_REQUIRED_PERMISSIONS = {"CREATE_ISSUES"}
 
    def init(jira_project_key, optional_param=42):
 
-       def execute(bug: BugzillaBug, event: BugzillaWebhookEvent) -> ActionResult:
+       def execute(context: ActionContext) -> ActionResult:
            print(f"{optional_param}, going to {jira_project_key}!")
            return True, {"result": 42}
 
@@ -27,11 +27,11 @@ Let's create a `new_action`!
 
    1. In the above example the `jira_project_key` parameter is required
    1. `optional_param`, which has a default value, is not required to run this action
-   1. `init()` returns a `__call__`able object that the system calls with the Bugzilla bug and WebHook event objects
+   1. `init()` returns a `__call__`able object that the system calls with the `ActionContext` object
    1. The returned `ActionResult` features a boolean to indicate whether something was performed or not, along with a `Dict` (used as a response to the WebHook endpoint).
 
-1. Use the `bug` and `event` information to perform the desired processing!
-1. List the required Jira permissions to be set on projects that will use this action in the `JIRA_REQUIRED_PERMISSIONS` constant. The list of built-in permissions is [available on Atlanssian API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permission-schemes/#built-in-permissions).
+1. Use the `context.bug`, `context.event`, `context.jira` information to perform the desired processing!
+1. List the required Jira permissions to be set on projects that will use this action in the `JIRA_REQUIRED_PERMISSIONS` constant. The list of built-in permissions is [available on Atlassian API docs](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permission-schemes/#built-in-permissions).
 1. Use the available service calls from `jbi/services` (or make new ones)
 1. Update the `README.md` to document your action
 1. Now the action `jbi.actions.my_team_actions` can be used in the YAML configuration, under the `module` key.