Hey all, Saw this on devcom list first :)
We had similar concerns in Apache Airflow project, although we had only 6 check boxes (and CI check to check if those are checked). We decided to remove any check boxes from template because contributors were too often confused by them and we already have enough CI checks. Even if there was "please add documentation/tests" checkbox we often had to ask people in comments for the same, so the initial check box was redundant. Instead we just asked people to add description or use meaningful title as those stay with us in form of git log or changelog. We still keep asking for tests, docs or change-log entry. This interaction in my opinion creates more welcoming experience than "here, this is the list of requirements, check all to be good citizen" especially that not every contributor knows when a docs or change-log entry is crucial. See related PR https://github.com/apache/airflow/pull/9896 I don't recall any degradation in PR quality. Cheers, Tomek On 2021/07/23 18:23:35, Zach Hoffman <zrhoff...@apache.org> wrote: > Hi all, > > A concern of mine has been that our Issue templates and our PR template are > too long, are confusing due to the verbose instructions, and take too much > effort to fill out, so I shortened them. > Link to the PR: https://github.com/apache/trafficcontrol/pull/6055 > I filled out the PR using the modified template, though, visually, there are > virtually no changes. > > In order to see the changes in action: > • Visit https://github.com/zrhoffman/trafficcontrol/issues/new/choose and > view the *Write* and *Preview* sections for *Bug report*, *Feature request*, > and *Improvement request* > • Visit > https://github.com/zrhoffman/trafficcontrol/compare/master...zrhoffman:my-branch > and view the *Write* and *Preview* sections after clicking the first *Create > pull request* button (but not the second) > > Biggest changes: > • For the Issue templates, the Apache License 2.0 is now commented in the > YAML section at the top, rather than being in HTML comments at the bottom. As > a result, Issues opened using these templates do not contain the Apache > License 2.0 (saves 16 lines for the user). > • Removed the "Additional Information" section and added "A description of > your PR goes here ↓" to the top of the PR template (saves 10 lines). Also > removed the "Anything else" sections from the Issue templates, since the > previous sections give the User the opportunity to write whatever they wanted > to say related to the Issue. > > Here's a summary of the line counts, before and after: > > Template Lines before Lines after > ------------------------------------------------------------------------------ > Pull Request template: 120 lines 75 lines > Bug report template: 78 lines 66 lines (44 lines seen > by the user) > Feature request template: 79 lines 62 lines (40 lines seen > by the user) > Improvement request: 79 lines 68 lines (46 lines seen > by the user) > > Changes that add clarity to the templates: > • Using more straightforward wording in the instructions. For example: > <!-- Describe how the bug manifests --> becomes > <!-- Describe how the bug happens --> > > Replaced "OR" in the PR template with explicit instructions, since it did not > explcitly tell the contributor what to do with those "OR" lines, and many > contributors either check the checkboxes without deleting one of the sides of > "OR" or skip that section entirely. > - [ ] This PR fixes #REPLACE_ME OR is not related to any Issue > becomes > - [ ] This PR fixes #REPLACE_ME > <!-- Or you can say > - [x] This PR is not related to any Issue > > - [ ] This PR includes tests OR I have explained why tests are > unnecessary > - [ ] This PR includes documentation OR I have explained why > documentation is unnecessary > - [ ] This PR includes an update to CHANGELOG.md OR such an update is > not necessary > - [ ] This PR includes any and all required license headers > - [ ] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY** (see > [the Apache Software Foundation's security > guidelines](https://www.apache.org/security/) for details) > > becomes > > - [ ] This PR includes tests <!-- If not, please delete this text and > explain why this PR does not need tests. --> > - [ ] This PR include documentation <!-- If not, please delete this > text and explain why this PR does not need documentation. --> > - [ ] This PR includes a CHANGELOG.md entry <!-- A fix for a bug from > an ATC release, an improvement, or a new feature should include a changelog > entry. --> > - [ ] This PR **DOES NOT FIX A SERIOUS SECURITY VULNERABILITY** (see > [the Apache Software Foundation's security > guidelines](https://apache.org/security) for details) > > • Refers to secur...@trafficcontrol.apache.org as the Apache Traffic Control > Security Team, not the Apache Software Foundation Security Team > > Also, it's not directly related to shortening the PR template, but the PR and > Issue templates' component lists have been updated Updated the components > list to mention T3C, GitHub Actions, and Ansible Roles (both under > Automation). > > Anyway, what do people think? Does anything need to be adjusted? > > -Zach >
