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 --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@community.apache.org For additional commands, e-mail: dev-h...@community.apache.org
