You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@community.apache.org by Zach Hoffman <zr...@apache.org> on 2021/07/23 18:22:09 UTC
Shorter and clearer Issue and PR templates
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 security@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-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org
Re: Shorter and clearer Issue and PR templates
Posted by Brian Thompson <se...@pm.me.INVALID>.
On 0726, Rich Bowen wrote:
>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.
Agreed, anything that lowers the bar to entry for getting users and dev
participating in the development of a project, I'm all for. Like Rich
said, having this available in the resource library would be very nice.
Teams could choose to adopt this approach or do their own thing. I
don't think a mandate is warranted here.
--
Best regards,
Brian T
Re: Shorter and clearer Issue and PR templates
Posted by Rich Bowen <rb...@rcbowen.com>.
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 <zr...@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 security@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-unsubscribe@community.apache.org
>> For additional commands, e-mail: dev-help@community.apache.org
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>
--
Rich Bowen - rbowen@rcbowen.com
@rbowen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org
Re: Shorter and clearer Issue and PR templates
Posted by Zach Hoffman <zr...@apache.org>.
Oops, wrong mailing list. Sorry
On 2021/07/23 18:22:09, Zach Hoffman <zr...@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 security@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-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org