# Review and change requests

A change request bundles drafts — pages, snippets, API references and navigation changes — so they can be reviewed and published together. You can use change requests on any site. When a site requires review, they are the only way anything goes live.

## Turn on required review

In the site's **Settings**, **Review**:

1. Turn on **Require review before publishing**.
2. Pick **Approvals needed to merge** (1 to 3).

While review is on, nobody publishes directly — Admins and Owners included. **Publish**, **Unpublish**, deleting a live page and changing a live page's address are refused; those changes go through a change request. Changes to the navigation (order and sections) also wait for a change request: readers keep seeing the navigation as it was until one is merged.

Turning review off is a site setting, so it needs permission to manage the site. When you turn it off, the navigation goes live as it is arranged in the editor.

## Who can review

Authorization comes from organization roles, not from the site:

- Anyone with `docs:page:write` can edit drafts and open change requests.
- Anyone with `docs:page:publish` can approve, request changes, merge and undo a merge — whether or not they were asked.
- Nobody approves their own change request.
- Reviews, merges and undoing a merge must be done by a person signed in to EvoHub. An API key cannot approve or merge, whatever its scopes.

The **Docs reviewer** preset gives a role exactly the approve-and-publish side. See [Roles and permissions](https://docs-dev.evohub.io/roles-and-permissions.md).

## Open a change request

:::steps
### Make your edits
Edit pages, snippets or API references and **Save draft**. Reorder the navigation if you need to.

### Start the request
Open **Change requests** in the site's menu and choose **New change request**. On a site that requires review, the page editor's **Open change request** button (in place of **Publish**) starts one for the page you are on.

### Pick the changes
Every draft that differs from what is live is listed — pages, translations, snippets, API references and **Navigation**. Tick the ones to include. A change can also take a live page off the site (**Unpublish**).

### Describe it and ask for review
Give it a **Title** and an optional **Description**, add **Reviewers**, and choose **Open change request**. Reviewers get a notification in Docs; they are whom you ask, not a gate.
:::

On a site with several versions, a change request belongs to one version and publishes to it.

## Review a change request

The change request shows each item as a diff of the live text against the draft (the navigation as an outline), plus a **Settings** block when page settings change. You can comment on the request as a whole or on a single item, and reply in threads.

At the bottom, leave an optional comment and choose **Approve** or **Request changes**. Any current request for changes blocks the merge.

### Approvals go stale

An approval is tied to exactly what the reviewer saw. If anything in the request changes after that — a draft is edited, an item is added or removed, the request is refreshed — earlier approvals are marked **Reset by later edits** and stop counting. Ask for another review.

## Merge

When the request has enough current approvals and nothing is waiting, it shows **Approved and ready to merge** and the **Merge** button. Merging publishes every item at once, in one step: either everything goes live or nothing does. Each published page gets a revision that records the change request.

### Outdated requests

Each item remembers the live copy it was drawn against. If someone publishes one of those pages some other way after the request was opened, the request is marked **Outdated** and cannot be merged. **Refresh** re-bases it on the current live copies; approvals reset.

### Undo a merge

A merged request offers **Undo merge**, which puts back exactly what was live before it — pages, snippets, API references and navigation. Undo is refused if any of those items was published again since.

### Close and reopen

**Close** sets a request aside without publishing; **Reopen** brings it back. The author or anyone who can publish can do either.

## Preview links

A preview link shows the whole site with the request's drafts in place, for people who do not use the console.

1. In the change request, under **Preview link**, choose **Create preview link**.
2. Copy the link right away; it is shown only once.

Anyone with the link sees the drafts, including pages limited to an audience on a private site, so share it like a password. Preview pages are never indexed or cached, and every link inside stays within the preview. The link stops working when the request is merged or closed, after 30 days, or when you choose **Turn off** or **New link**.

Preview links open on the site's own domain, so the site needs an active custom domain. See [Connect a custom domain](https://docs-dev.evohub.io/docs-custom-domain.md).

## Rollbacks under review

On a site that requires review, rolling a page back to an earlier revision puts that revision in the draft and opens a change request for it instead of publishing.

## GitHub and imports under review

When a site requires review, a GitHub sync opens (or updates) one change request instead of publishing, and an import into an existing site arrives as one change request. See [Docs as code with GitHub](https://docs-dev.evohub.io/github-sync.md) and [Import and export](https://docs-dev.evohub.io/import-and-export.md).

## Notifications

**Notifications** in the Docs menu lists review requests and what happened to your change requests: approvals, requests for changes, comments and merges. Notifications are in the console only; Docs does not email them.

## Related

- [Docs overview](https://docs-dev.evohub.io/docs-overview.md)
- [Roles and permissions](https://docs-dev.evohub.io/roles-and-permissions.md)
- [Docs as code with GitHub](https://docs-dev.evohub.io/github-sync.md)