Staging review content

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.

Setting up the review environment

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.

    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 master) 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 master to push the content live.

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

Review workflows

Option 1: Linear workflow

One option is to use the review branch for previewing content before pushing it to master. 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 master 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 master branch. If you ever make changes to the master 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 master TO review.

Option 2: Multiple feature sets

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

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

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 master branches are in sync. For example, run a pull request FROM master TO review (it’s usually the opposite direction).

  • 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 master, 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 master 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 master branch. To keep the review branch up-to-date and avoid potential conflicts, you can pull changes from master to review.

  1. Create a pull request.

  2. Set master as the source and review as the destination.

    pr from master to stage

  3. Click Create pull request.

  4. If there are Git conflicts, resolve them.

    See Resolve Git conflicts.

  5. When validation passes, merge the pull request so that review is in sync with master.

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 and enter git reset -hard master and then git push --force (it’s the equivalent of deleting/re-creating the branch).

On this page