Skip to content

docs: Document email notifications fired by the change request workflow #7505

@Holmus

Description

@Holmus

Current state

The change requests docs page mentions email notifications only once: "These individuals will receive an email notification about the Change Request." This refers to assignees being notified at CR creation. The page does not document the full set of email notifications that the workflow actually fires.

What the code does (verified in api/features/workflows/core/models.py)

Two email notifications fire for individual approvers:

  1. send_email_notification_to_assignee — fires on AFTER_CREATE of a ChangeRequestApproval with approved_at=None. Notifies the assignee that they have a pending approval.
  2. send_email_notification_to_author — fires on AFTER_CREATE or AFTER_UPDATE when approved_at transitions to a non-null value. Notifies the CR author that their CR has been approved.

A group-level notification also fires via background task notify_group_of_change_request_assignment.delay(...) when a CR is assigned to a group.

Gaps that should be made explicit in docs

  • Both individual email notifications above should be documented (pending-approval to assignee, approval-granted to author).
  • Group assignment notification path should be documented.
  • Customers consistently ask whether external notifications exist; the docs implying "no" is causing avoidable workaround conversations.

What the code does NOT do (worth calling out so customers don't expect it)

  • No email is sent when a CR is committed (only audit log entries are created for affected feature states).
  • There is no first-class CR rejection; "rejection" = delete, no email.
  • No webhook events for CR lifecycle changes were found in the codebase.

Suggested docs additions

A "Notifications" subsection under the change requests page enumerating the two emails + group notification that fire, plus a brief note on what is not notified externally.

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation updates

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions