There are two main reasons for creating a review branch:
If you create a branch in your repo called
review, the following things occur when you commit to this
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 branch does not need to be permanent. You can delete and re-create this branch just like any branch.
review workflow is configured to work with any repo that is set up to use the EXL pipeline.
Create a branch called
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.
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.
View the Slack notification summary. If the job is successful, links to the modified articles are listed at the bottom of the summary.
(Optional) Send links to reviewers and ask for feedback.
When ready, submit your content to
main to push the content live.
One option is to submit a PR from
main. For some workflows, you might submit a PR from a different branch to
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.
This option works well if the product team releases new features at the same time.
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.
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.
By using this approach, you can use the review branch for multiple upcoming features that release at different times.
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. For example, run a pull request FROM main 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.
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.
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.
Create a pull request.
main as the source and
review as the destination.
Click Create pull request.
If there are Git conflicts, resolve them.
When validation passes, merge the pull request so that
review is in sync with
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).