Thank you, Zach and Tomek. Our PR/issue templates have been in need of a revamp, and the Apache Airflow template provides some good inspiration.
- Rawlin On Fri, Jul 23, 2021 at 1:19 PM Tomasz Urbaszek <turbas...@apache.org> wrote: > > 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 > >
