(NFC) PULL_REQUEST_TEMPLATE.md - Improve suggestions for under-the-hood/non-UI changes
authorTim Otten <totten@civicrm.org>
Tue, 12 Nov 2019 21:48:33 +0000 (13:48 -0800)
committerTim Otten <totten@civicrm.org>
Tue, 12 Nov 2019 22:39:36 +0000 (14:39 -0800)
commit17ababa7f50b6972dc0493664c8c11dd0001c2e4
treef3513bb55c17bd558efb62e29f5edd78c646fc6d
parent671232003fc7b673140e5407287b6a06af97c15d
(NFC) PULL_REQUEST_TEMPLATE.md - Improve suggestions for under-the-hood/non-UI changes

Overview
----------------------------------------

The "pull-request template" is presented to a developer when submitting a
proposed change; it prompts them to fill in additional information.  This
revision aims to make the prompts more useful in the common case where change
does *not* involve the user-interface.

Before
----------------------------------------

The `PULL_REQUEST_TEMPLATE.md` suggests that the "Before" and "After" should
be demonstrated with screenshots.

This is wonderful for UI-oriented changes.

However, if a change is focused under-the-hood (APIs, data-structures,
class-hierarchies, refactorings, etc) - then the prompt is kind of
meaningless/non-applicable.  A meaningless prompt understandably elicits
weak responses like "*Before: Some incorrect metadata*" or "*After: It's
less confusing*".

After
----------------------------------------

The `PULL_REQUEST_TEMPLATE.md` still recommends using concrete example in
"Before"/"After", but it's more open about what that means.

For a UI-oriented change, it means screenshots.  For an
API/technical-service change, it means code-snippets.
.github/PULL_REQUEST_TEMPLATE.md