From 6d288e382c2fa9c5ada5cfd5c1ab85e6a3866d76 Mon Sep 17 00:00:00 2001 From: Tim Otten <totten@civicrm.org> Date: Thu, 1 Feb 2018 14:50:15 -0800 Subject: [PATCH] Update review.md - r-explain --- docs/standards/review.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/standards/review.md b/docs/standards/review.md index a8b7fe58..aac13c89 100644 --- a/docs/standards/review.md +++ b/docs/standards/review.md @@ -22,9 +22,11 @@ You may conduct a structured review, checking each standard in turn. Doing this _Standard code: `r-explain`_ -This change will likely be inspected by current+future colleagues who (a) want to understand what's improved in the next release and/or (b) want to understand why the system works the way it does. +Ensure the PR has an adequate explanation. -Ensure that PR has an adequate explanation. The explanation may be written directly in the PR description, or it could be linked in a [JIRA issue](/tools/issue-tracking.md#jira), [Gitlab issue](http://lab.civicrm.org/), or [StackExchange](https://civicrm.stackexchange.com/) thread. +If you were a site-builder reading the PR-log/release-notes and drilled into this PR, would you understand the description? If you were debugging a problem and traced the change back to this PR, would you understand why the change was made? + +The explanation may be written directly in the PR description, or it could be linked in a [JIRA issue](/tools/issue-tracking.md#jira), [Gitlab issue](http://lab.civicrm.org/), or [StackExchange](https://civicrm.stackexchange.com/) thread. Exception: [NFC](/tools/git.md#nfc) and [WIP](/tools/git.md#wip) PRs may not need a detailed explanation. -- GitLab