Review and Approval Workflows

Overview

This guide covers the review and approval processes, focusing on JIRA-based review requests and GitHub PR review procedures.

Requesting Reviews or Example Code from Dev via JIRA

Create a JIRA with the following settings:

• Project = CLD or SDK
• Type = Task
• Subject: "Doc review request:xxxx" or "Example code needed: xxx"
• Assigned to = R&D Team
• Status = Ready for dev
• Linked issue = Blocks
• Due Date = date that's at least 8-10 days away unless urgent

GitHub PR Review Process

Merging PRs

As a rule, EVERY PR must be reviewed and approved by at least one person before merging.

• Most feature PRs should get both a dev (and/or other SME - i.e. relevant product manager, CS engineer, etc) and doc review.

• For big issues, it generally makes sense to get all the dev/SME reviews implemented first, and only then ask for a doc review of the updated content.

• If one or more of your SME reviewers aren't familiar/comfortable with GitHub, create the PR, and then copy-paste the doc preview to a GoogleDoc & have them comment there so you can implement the changes. (Usually helpful to also put these on staging so the reviewer can see what it will really look like). In this case, you should still get a doc review & approval in the PR itself.

• Even very tiny reviews where you only add a small code or text fix and can't imagine there's something to correct, should generally get at least one dev or doc review.

• Doc members do have permission to override the reviewer requirement and merge a PR without any review or approval. But this option should be the exception to the rule. Use only when it's an extremely small change and it needs to go out urgently and no one is available to quickly review it.

GitHub Assignees

When you set an assignee on a PR, their profile avatar shows in the main PR page, and you can also filter by assignees. Among other things, this can help you to filter for all PRs that are waiting for you (for example, because you are an assigned reviewer, or because you are the owner and the ball is back in your court).

The "Assignee(s)" for each PR in cld_docs or content_render should always be set to the person/people who next need to do something on the PR to take it forward.

• When you first create a PR and assign reviewer(s), you should also set the reviewer(s) as the assignee(s).
  Note

  In general, you shouldn't be creating a PR until you are ready for a review, but if for some reason you create one & it's not yet ready to be reviewed, set yourself as the assignee.
• When a reviewer finishes, they should remove their name from the assignee list (but NOT from the reviewer list) & set the PR owner as assignee (so the owner can implement feedback, release, or follow up with remaining reviewers). (If there are other reviewer assignees still in the list, don't remove those when you replace your name as reviewer with the owner name.)
• If you are the owner and you are ready to merge a PR, make sure no one other than yourself is in the Assignee list, and only people who actually reviewed are in the reviewer list. Remove names that were set in either of these lists, but didn't actually take part in the PR.
• If your dev reviewers don't follow this process when they finish a PR review for you, you might have to remind them or just update it yourself.