On 7/23/21 2:22 PM, Zach Hoffman wrote:
Oops, wrong mailing list. Sorry
Acknowledged ... but ...
I wonder if it would be useful to have this kind of thing in our project
resource library. This kind of thing - going this far out of your way to
make it easy for people to participate in your project - is just so
awesome, and so much more than many of our projects do. Having something
like this in a place where other projects can access it could be really
helpful to many of our projects which struggle to attract new participants.
--Rich
On 2021/07/23 18:22:09, 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@community.apache.org
For additional commands, e-mail: dev-h...@community.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@community.apache.org
For additional commands, e-mail: dev-h...@community.apache.org
--
Rich Bowen - rbo...@rcbowen.com
@rbowen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@community.apache.org
For additional commands, e-mail: dev-h...@community.apache.org
