From 17ababa7f50b6972dc0493664c8c11dd0001c2e4 Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Tue, 12 Nov 2019 13:48:33 -0800 Subject: [PATCH] (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 | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 85e7f8f59d..e9760193f6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,18 +1,20 @@ Overview ---------------------------------------- -_A brief description of the pull request. Try to keep it non-technical._ +_A brief description of the pull request. Keep technical jargon to a minimum. Hyperlink relevant discussions._ Before ---------------------------------------- -_The current status. Please provide screenshots or gifs ([LICEcap](http://www.cockos.com/licecap/), [SilentCast](https://github.com/colinkeenan/silentcast)) where appropriate._ +_What is the old user-interface or technical-contract (as appropriate)?_ +_For optimal clarity, include a concrete example such as a screenshot, GIF ([LICEcap](http://www.cockos.com/licecap/), [SilentCast](https://github.com/colinkeenan/silentcast)), or code-snippet._ After ---------------------------------------- -_What has been changed. Please provide screenshots or gifs ([LICEcap](http://www.cockos.com/licecap/), [SilentCast](https://github.com/colinkeenan/silentcast)) where appropriate._ +_What changed? What is new old user-interface or technical-contract?_ +_For optimal clarity, include a concrete example such as a screenshot, GIF ([LICEcap](http://www.cockos.com/licecap/), [SilentCast](https://github.com/colinkeenan/silentcast)), or code-snippet._ Technical Details ---------------------------------------- -_If the PR introduces noteworthy technical changes, please describe them here. Provide code snippets if necessary_ +_If the PR involves technical details/changes/considerations which would not be manifest to a casual developer skimming the above sections, please describe the details here._ Comments ---------------------------------------- -- 2.25.1