Fix #606, fix #936: Polish actions docs (#1072)

Author: leplatrem

.github/ISSUE_TEMPLATE/new-config.yaml

@@ -53,6 +53,11 @@ body:
         - label: Issue Type (please provide mapping, eg. `enhancement` -> `Story`)
         - label: Status (please provide mapping, eg. `RESOLVED` -> `Done`)
         - label: Resolution (please provide mapping, eg. `WONTFIX` -> `Won't do`)
+        - label: Priority
+        - label: Severity
+        - label: Issue points
+        - label: Comments
+        - label: Keywords (as labels)
         - label: Whiteboard tags (as labels)
         - label: Assignee (Bugzilla and Jira user must use the same email address)
         - label: Field changes (recorded as comments on the issue)

README.md

@@ -9,10 +9,10 @@ System to sync Bugzilla bugs to Jira issues.
 ## Caveats
 - The system accepts webhook events from Bugzilla
 - Bugs' `whiteboard` tags are used to determine if they should be synchronized or ignored
-  - Only public bugs are eligible for sychronization.
+  - **Only public bugs** are eligible for synchronization.
 - The events are transformed into Jira issues
 - The system sets the `see_also` field of the Bugzilla bug with the URL to the Jira issue
-  - No other information is sychronized from Jira to Bugzilla.
+  - No other information is synchronized from Jira to Bugzilla.
 
 > **Note:** whiteboard tags are string between brackets, and can have prefixes/suffixes using
 > dashes (eg. ``[project]``, ``[project-fx-h2]``, ``[backlog-project]``).
@@ -67,6 +67,7 @@ graph TD
 
    - If you are not an admin of the Jira project, contact the admin or reach out to `#jira-support` in Slack to determine how best to request the changes described above
 
+1. Some actions require specific fields on the create and update screens in Jira. Double check the [actions documentation](docs/actions.md)
 1. Once your configuration is merged and a JBI release is deployed, create a bug in Bugzilla and add your whiteboard tag to the bug. Note that the tag must be enclosed in square brackets (eg. `[famous-project]`). You should see an issue appear in Jira
    - If you want to start syncing a bug to a Jira issue that already exists, add the issue's link to the `See Also` section of the Bugzilla bug before you add the whiteboard tag
 

docs/actions.md

@@ -138,23 +138,25 @@ linked Jira issue status to "Closed". If the bug changes to a status not listed
 - `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.
+  then the assignee is cleared from the Jira issue.
+  **Requirements**: 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.
+  **Requirements**: ``resolution`` field must be present on issue forms (or configure `jira_resolution_field`).
 - `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_priority`
+  **Requirements**: ``priority`` field must be present on issue forms (or configure `jira_priority_field`).
 - `maybe_update_issue_resolution`
 - `maybe_update_issue_severity`
+  **Requirements**: ``customfield_10319`` field must be present on issue forms (or configure `jira_severity_field`).
 - `maybe_update_issue_status`
+- `maybe_update_issue_points`
+   **Requirements**: ``customfield_10037`` field must be present on issue forms (or configure `jira_cf_fx_points_field`).
 - `create_comment`
 - `sync_keywords_labels`
 - `sync_whiteboard_labels`
 - `maybe_update_components`: looks at the component that's set on the bug (if any) and any components added to the project configuration with the `jira_components` parameter (see above). If those components are available on the Jira side as well, they're added to the Jira issue
-