Skip to content

docs: document CR scope, notifications and non-notification events#7549

Open
SahilJat wants to merge 1 commit into
Flagsmith:mainfrom
SahilJat:docs/change-requests-scope-and-notifications
Open

docs: document CR scope, notifications and non-notification events#7549
SahilJat wants to merge 1 commit into
Flagsmith:mainfrom
SahilJat:docs/change-requests-scope-and-notifications

Conversation

@SahilJat
Copy link
Copy Markdown
Contributor

  • I have read the Contributing Guide.
  • I have added information to docs/ if required so people know about the feature.
  • I have filled in the "Changes" section below.
  • I have filled in the "How did you test this code" section below.

Changes

Closes #7505
The Change Requests docs page had two gaps that were causing avoidable
support conversations:

  1. Scope was not documented — the page said "attempting to change a flag
    value will prompt you to create a new Change Request" without clarifying
    that identity-level overrides are intentionally excluded from the workflow
    and go live immediately.

  2. Notifications were not documented — the page mentioned assignee emails
    only once in passing. The full set of emails that fire (pending-approval to
    assignee, approval-granted to author, group assignment notification) was
    not described anywhere. Equally important, what does not trigger a
    notification (commit, deletion, webhooks) was also undocumented, leading
    customers to expect behaviour that does not exist.

**Changes made **

  • Added a Scope of Change Requests section with a table showing which
    feature state types require a CR and which do not, with an explanation of
    why identity overrides are excluded (they do not participate in the
    versioning system the CR workflow is built on)
  • Added a tip recommending segment-based targeting for teams that need
    approval gates on all changes
  • Added a Notifications section with a table of all email notifications
    that fire during the CR lifecycle, and an explicit list of events that do
    not trigger notifications (commit, deletion, webhooks)
  • Updated the "Create a Change Request" section to clarify that the prompt
    applies to environment defaults and segment overrides, not all flag changes

Both additions are verified against the actual implementation in
api/features/workflows/core/models.py.

How did you test this code?

This is a documentation-only change — no code was modified.

Verified the described behaviour against the source code:

  • Scope — confirmed via FeatureState.type property and is_live
    property in api/features/models.py that identity overrides bypass
    versioning and are live immediately
  • Notifications — confirmed via send_email_notification_to_assignee,
    send_email_notification_to_author, and
    notify_group_of_change_request_assignment hooks in
    api/features/workflows/core/models.py that the documented emails are the
    complete set
  • Non-notifications — confirmed no email fires on commit, no rejection
    flow exists, and no CR lifecycle webhook events are present in the codebase

@SahilJat SahilJat requested a review from a team as a code owner May 20, 2026 06:15
@SahilJat SahilJat requested review from Holmus and removed request for a team May 20, 2026 06:15
Copy link
Copy Markdown

@claude claude Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@vercel
Copy link
Copy Markdown

vercel Bot commented May 20, 2026

@SahilJat is attempting to deploy a commit to the Flagsmith Team on Vercel.

A member of the Team first needs to authorize it.

@github-actions github-actions Bot added the docs Documentation updates label May 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: Document email notifications fired by the change request workflow

1 participant