Change requests initial documentation for beta

website/docs/change-requests.mdx

@@ -0,0 +1,152 @@
+---
+id: change-requests
+title: Change Requests & Scheduled Changes (Beta)
+description: Propose, schedule, and review feature flag changes with the ConfigCat approval flow.
+---
+
+:::info
+**Beta Feature**: Change Requests & Scheduled Changes is in closed beta. We're now collecting feedback from real-world usage to fine-tune the experience.
+:::
+
+A _Change Request_ is a bundle of feature flag changes that you prepare on the Dashboard without publishing them immediately.
+You can propose a change for manual publishing later, or schedule it to be applied automatically at a specific time.
+
+Typical use cases:
+
+- **Scheduled release** - you want a feature turned on next Monday at 9 AM without being at your desk.
+- **Approval before go-live** - you work in a regulated environment where a colleague must review every change before it reaches production.
+- **Draft and collaborate** - you want to prepare changes, collect feedback in comments, and only publish when the team agrees.
+
+## How does it work?
+
+Feature flag changes in ConfigCat can be:
+
+- **Published immediately** - the classic way, the change takes effect right away.
+- **Proposed** - saved as a change request for later manual publishing.
+- **Scheduled** - saved as a change request that ConfigCat applies automatically at a selected date and time.
+
+If an environment is configured as _approval-required_, changes cannot be applied immediately. A change request must be opened, reviewed, and approved by another member before it can be published. This also applies to scheduled changes - a scheduled change request is only applied on schedule if it has been approved.
+
+## Permissions
+
+### Who can create change requests?
+
+Only members with **Read/Write** (feature management) permission in the environment can propose or schedule changes.
+
+### Approval flow product preference
+
+The **Approval flow** product preference controls which environments require approval.
+
+You can enable it:
+- for the entire product, or
+- per environment.
+
+When an environment is approval-required, all feature flag changes must go through a change request. The only exception is the **Can bypass approval** permission, described below.
+
+### Change request approvals permission
+
+Permission groups include a **Change request approvals** permission with the following values:
+
+- **Cannot approve** - The member cannot approve any change request.
+- **Can approve others** - The member can approve change requests opened by other members.
+- **Can bypass approval** - The member can approve any change request, or apply changes directly without going through the approval flow.
+
+This permission can be set product-wide or overridden per environment.
+
+In approval-required environments:
+- Members with **Read/Write** can create change requests (propose or schedule changes).
+- Members with at least **Can approve others** can approve change requests.
+- Members with **Read/Write** can apply an approved change request.
+- Members with **Can bypass approval** can approve any change request, or apply changes directly, skipping the approval step entirely.
+- Members with at least **Can approve others** can close any change request.
+
+:::info
+**Can bypass approval** is intended for firefighting. The default behavior is always the full approval flow for both proposed and scheduled changes. To bypass approval for a specific change, the user must explicitly opt in — it is never automatic.
+
+For scheduled change requests specifically, a member with **Can bypass approval** can configure a given scheduled change request to be applied on schedule without requiring prior approval. This opt-in must be set per change request.
+:::
+
+## Lifecycle of a change request
+
+### Ownership and editing
+
+A change request can only be edited by its owner. Other members can:
+- comment on the request,
+- approve it (if they have the appropriate permission),
+- close it (if they have at least **Can approve others**).
+
+### Comments, notifications, and activity
+
+Each change request supports comments for team discussion. Email notifications are sent for important events (approvals, comments, status changes). The activity log records everything that happened on the request.
+
+### Re-approval after edits
+
+If the owner edits a change request — for example, modifying the feature flag values or changing the schedule — all existing approvals are dropped. The request must be reviewed and approved again before it can be applied.
+
+## Statuses
+
+- **Open** - The change request has been created and is waiting to be applied.
+- **Applied** - The changes have been published.
+- **Closed** - The change request was closed without being applied. Closed change requests cannot be reopened.
+
+### Scheduled request fallback
+
+If a scheduled change request cannot be applied at the planned time — for example, because it was never approved — the schedule is removed and the request becomes a regular open (proposed) change request. You can then fix the issue and apply it manually or even re-schedule it.
+
+### Needs approval
+
+A change request shows **Needs approval** when it is in an approval-required environment and has not yet been approved.
+
+### Needs attention
+
+A change request shows **Needs attention** when there is a problem that prevents it from being applied, either manually or on schedule. The issue must be resolved before the request can proceed.
+
+Possible causes:
+
+- **Conflicting changes** — changes for the same feature flags have been published since the change request was opened. See [Conflict handling](#conflict-handling).
+- **Owner is unavailable** — the owner left the organization or lost **Read/Write** permission in the environment. Another eligible member must claim the change request.
+- **Missing mandatory notes** — mandatory notes were enabled on the environment after the change request was created, and the change request does not have notes.
+- **Circular dependency** — a change was published since the change request was opened, and applying the request now would create a circular dependency through prerequisite flags.
+
+## Conflict handling
+
+When you open a change request, ConfigCat notifies you if any other open change request already includes the same feature flags.
+
+This matters because if two change requests modify the same flag, the one applied first will mark the other as invalid. An invalid change request cannot be applied until its conflicts are resolved.
+
+The conflict resolver shows you:
+- the changes your change request proposes, and
+- the changes that have been published since you opened it.
+
+You can resolve conflicts using one of the following options:
+
+### Auto merge
+
+Automatically merges your proposed changes with the currently published state. This option is only available when the system is able to merge the changes safely.
+
+:::tip
+Always review the merged result carefully before applying to make sure it reflects the correct values.
+:::
+
+### Accept theirs and re-apply your changes
+
+Starts resolving the conflict from the currently published values, then lets you re-apply your intended changes on top. Use this when you want your changes applied to the current state of the flag. This is the recommended option when Auto merge is not available.
+
+### Accept yours and re-apply the published changes
+
+Starts from your proposed values, then lets you apply the changes that were published since you opened the request. Use this when you want the published changes layered on top of your proposal.
+
+### Remove setting from change request
+
+Removes this particular feature flag from the change request, discarding its changes. This option is only available when the change request contains more than one feature flag.
+
+### Close change request
+
+Closes the entire change request. Use this when the conflict should not be resolved and the changes should not be applied at all.
+
+## Current limitations
+
+The approval flow currently applies to feature flag value changes only. The following actions do not require a change request or approval:
+
+- Creating or deleting a feature flag.
+- Changes to segments.

website/sidebars.ts

@@ -37,6 +37,7 @@ const docs: SidebarConfig = [
         ],
       },
       'advanced/predefined-variations',
+      'change-requests',
     ],
   },
   {

website/src/pages/index.js

@@ -17,6 +17,7 @@ const features = [
       { url: 'organization', title: 'Organization & Roles' },
       { url: 'targeting/targeting-overview', title: 'Targeting' },
       { url: 'advanced/predefined-variations', title: 'Predefined Variations vs Free‑Form Values' },
+      { url: 'change-requests', title: 'Change Requests & Scheduled Changes (Beta)' },
     ],
   },
   {