Documentation Experience League Authoring Guide

Stage review content

Last update: May 23, 2026

NOTE

The review environment is nearly complete for GHEC. We’re still working out some publishing issues, but using review is available.

There are two main reasons for creating a review branch:

To stage content reviews for Adobe employees prior to a product release.
To preview content for longer periods of time without risking accidental publishing.

Whenever you have a valid commit to the review branch, you’ll get a Slack notification that includes the review URLs of modified files. However, there is no validation of the review branch. See the next section for details.

The review branch does not need to be permanent. You can delete and re-create this branch just like any branch.

Set up the review environment workflow-overview

The review workflow is configured to work with any repo that is set up to use the EXL pipeline.

Create a branch called review. If an older review branch exists, delete it or rename it.
For the first edit to the new branch, add dummy metadata to the TOC.md file, such as nudge: true or color: red. This will trigger the entire guide to be published to review.

The current publishing issues we’re experiencing in production are also affecting the review environment. If you’re unable to update your content on the review server, please reach out to us on Slack > sccm-assistance.
Commit changes to the review branch.

Content is published as soon as possible. You should receive a Slack notification that lists the updated files.

The review branch does NOT validate the content.
(Optional) Send links to reviewers and ask for feedback.

Validating content in the review branch

Create a pull request from the review branch to the main branch.
If validation fails, make the appropriate edits.
Close the PR without merging.

Committing directly to the review branch or using a PR

You can either commit directly to the review branch or submit a PR from another branch to review.

If you create a branch that feeds into review, remember to specify review when you create the pull request. By default, the base branch (usually main) is selected whenever you create a PR, so be careful you don’t accidently submit a PR against the wrong branch.

Review workflows

Option 1: Linear workflow

One option is to use the review branch for previewing content before pushing it to main. In this workflow, you would submit content to the review branch, either as a direct commit or as a pull request from a separate branch. Then, after review, you would push the content from the review branch to the main branch.

linear stage image

This option works well if the product team releases new features at the same time.

TIP

Keep your review branch in sync with the main branch. If you ever make changes to the main branch but not the review branch, you’ll want to sync the branches on occasion.

One method is to delete/re-create the review branch, such as after a release. Another method is to create a pull request FROM main TO review.

Option 2: Multiple feature sets

Another option is to use the review branch only for internal reviews, not as a feeder into main.

For example, suppose that you have multiple releases coming up, and these releases will go live at different times. In this scenario, you would create branches for each upcoming feature set, such as “new-admin-rules” and “updated-config-options”. In order to send out review links to your team, you would submit a PR from these feature branches to the review branch.

multiple features stage image

When you get feedback, you edit the feature branches. When the feature set goes live, you then submit a PR from the feature branch (NOT the review branch) to main.

linear stage image

By using this approach, you can use the review branch for multiple upcoming features that release at different times.

TIP

When using Option 2, avoid problems by doing this:

When you’re ready to start working on the review branch, make sure the review and main branches are in sync. See the next section on keeping the review branch up to date.
When working on a PR from feature branch to review branch, you might get a “conflict” message that prompts you to update the feature branch with review content. STOP! Doing so can bring in unwanted edits from other feature branches that might “pollute” your feature branch.

As a final precaution, when you merge from the feature branch to main, check the PR to make sure only the changes you made in the feature branch are included in the PR.

Keep review branch up-to-date with main branch

A common workflow is to use the review branch for documenting features in an upcoming release, which can be weeks or months in the future. While you’re making edits in review, you or other members of your team might be making changes to the main branch. To keep the review branch up-to-date and avoid potential conflicts, you can pull changes from main to review.

In GitHub Desktop, select the review branch.
Click the Current Branch drop-down menu and choose Choose a branch to merge into review at the bottom of the menu.
Select the main branch to merge into review, and then click Create a merge commit.
If there are Git conflicts, resolve them.

See Resolve Git conflicts.

TIP

If you’re willing to blow away the changes to the review branch, you can select the review branch in GitHub Desktop, choose Repository > Open in Terminal and enter git reset --hard main and then git push --force (it’s the equivalent of deleting/re-creating the branch).

If you’d rather not use command lines, you can select the review branch in GitHub Desktop, copy the help files in your repo to a different folder, and then select main again and replace the help folder. Create a new branch and submit a PR so that you can revert it.

Configure review for v2 (Admin) config

https://github.com/organizations/Adobe-Enterprise-Docs/settings/installations/123753477 (GHEC)

Also, update v2 paths in https://github.com/adobe-experience-league/exlm-converter/settings/environments (public github).

recommendation-more-help

authoring-guide-help-main-guide