DocumentationExperience League Authoring Guide

Stage review content

Last update: Fri Sep 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

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.

If you create a branch in your repo called review, the following things occur when you commit to this review branch:

  • Jenkins validation occurs.
  • If validation passes, content is output to https://experienceleague-review.corp.adobe.com, available only behind the Adobe firewall.

Whenever you have a valid commit to the review branch, you’ll get a Slack notification that includes the review URLs of modified files.

Review slack summary

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.

  1. Create a branch called review.

  2. Commit changes to the review branch.

    You can either commit directly to the review branch or submit a PR from another branch to review. When you commit changes to review, a Jenkins validation is kicked off.

    note important
    IMPORTANT
    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.

  3. View the Slack notification summary. If the job is successful, links to the modified articles are listed at the bottom of the summary.

  4. (Optional) Send links to reviewers and ask for feedback.

  5. When ready, submit your content to main to push the content live.

    One option is to submit a PR from review to main. For some workflows, you might submit a PR from a different branch to main.

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.

    staging-out-of-date

  • 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.

  1. In GitHub Desktop, select the review branch.

  2. Click the Current Branch drop-down menu and choose Choose a branch to merge into review at the bottom of the menu.

    pr from main to stage

  3. Select the main branch to merge into review, and then click Create a merge commit.

  4. 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.
recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda