ADMIN: Create separate issue templates for different usecases #33187

ShaharNaveh · 2020-03-31T17:54:33Z

revival of #31551 originally opened by @jschendel

I recall this being mentioned on one of the core dev calls a few months back, and took inspiration from rapidsai/cudf for the various templates.

Added templates for the following use cases:
* Bug Report
  
  * This is largely the same as the current issue template

* Documentation Enhancement

* Documentation Error

* Feature Request

* Submit Question
  
  * This attempts to direct users to StackOverflow for usage questions
We could also add a Blank Template for opening an issue without any template provided, but opted not to do that for now, as I don't want to encourage people to bypass these templates. Could certainly add one if there's a consensus that we want this.

I've created a local repo where you can see these templates in action since I couldn't figure out another way to actually display these. Click the "New Issue" button to see what these changes would look like.

mroeschke · 2020-03-31T19:34:21Z

.github/ISSUE_TEMPLATE/bug_report.md


 ```python
 # Your code here

 ```
+
+**Note**: Please read [this guide](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) detailing how to provide the necessary information for us to reproduce your bug.


IMO, this should go before the Code Sample

mroeschke · 2020-03-31T19:36:32Z

.github/ISSUE_TEMPLATE/bug_report.md

 #### Problem description

-[this should explain **why** the current behaviour is a problem and why the expected output is a better solution.]
+[this should explain **why** the current behaviour is a problem and why the expected output is a better solution]

 **Note**: We receive a lot of issues on our GitHub tracker, so it is very possible that your issue has been posted before. Please check first before submitting so that we do not have to handle and close duplicates!


As a suggestion. I think we should change these two **Note** sections into checkboxes like

- [ ] I have checked that issue has not already been reported - [ ] I have confirmed this bug exists on the latest version of pandas - [ ] I have confirmed this bug exists on the master branch of pandas

More succinct than these sections IMO.

Inspired how Numba does their bug reports: numba/numba#4735

mroeschke · 2020-03-31T19:38:56Z

.github/ISSUE_TEMPLATE/wrong_or_missing_documentation.md

+
+#### Location of the documentation
+
+[this should provide a description of what documentation you believe needs to be fixed/improved]


I think we should also encourage a link to the documentation that they want to see improved.

TomAugspurger

Thanks for reviving this.

TomAugspurger · 2020-03-31T21:29:42Z

.github/ISSUE_TEMPLATE/feature_request.md

+
+#### Describe the solution you'd like
+
+[this should provide a description of the feature request, e.g. "`DataFrame.foo` should get a new parameter `bar` that [...]"]


I've found asking people to "write a docstring" to be helpful in clarifying what people are asking for.

.github/ISSUE_TEMPLATE/feature_request.md

XREF: pandas-dev#33187 (comment)

.github/ISSUE_TEMPLATE/submit_question.md

.github/ISSUE_TEMPLATE/feature_request.md

.github/ISSUE_TEMPLATE/bug_report.md

.github/ISSUE_TEMPLATE/documentation_improvement.md

Co-Authored-By: Tom Augspurger <[email protected]>

Co-Authored-By: Joris Van den Bossche <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.md

mroeschke · 2020-04-01T16:10:30Z

.github/ISSUE_TEMPLATE/bug_report.md

+name: Bug Report
+about: Create a bug report to help us improve pandas
+title: "BUG:"
+labels: ""


I'd say we should use this label: feature to automatically tag the issue with the appropriate label. For this template Bug and similarly for the others.

https://github.community/t5/How-to-use-Git-and-GitHub/Apply-labels-automatically-at-issue-creation/td-p/10719#

Just making sure before I make the changes, the labels for each file should look like this:

bug_report: Bug

documentation_improvement: Docs

feature_request: Enhancement?

submit_question: "Usage Question"

I was originally on the fence about automatically adding labels because it could make it harder to distinguish what has been triaged vs. what hasn't, since I currently look for the presence of labels to determine if something has been triaged, and automatically adding labels would make it less clear whether a triage has occurred or not.

A potential workaround here is to also automatically add a new "Needs Triage" label and then remove it as part of the triage process. Or maybe this is only an issue on my part, in which case I can work around it.

feature_request: Enhancement?

We don't have a label for feature requests

We don't have a label for feature requests

We typically use the "Enhancement" label for this, so I think what you've proposed above is good.

Yeah, I've seen a couple variants of this: rapidsai/cudf automatically adds a generic "? - Needs Triage" label, scikit-learn/scikit-learn adds a "Bug: triage" just to bug reports.

Numba has a need triage label: https://github.com/numba/numba/issues?q=is%3Aissue+is%3Aopen+label%3Aneedtriage

I'd be in favor in autotagging with <Bug/Doc/Enhancement/...> + Need Traige, and then Need Triage can be removed once someone has commented (and can be replace with a more specific label like IO CSV for example)

I've also been making an effort to tag older issue with one of Bug/Doc/Enhancement/... which will be useful in the future for developing metrics about total number of issues per category.

@mroeschke ATM Need Triage label does not exists.
Should I wait for it to be created? or just edit this pull request to auto-assign the label Need Triage and the label will be created later.

I went ahead and just created a Needs Triage label so it should be available now.

Thank you @mroeschke

XREF: pandas-dev#33187 (comment)

XREF: pandas-dev#33187 (comment) pandas-dev#33187 (comment)

.github/ISSUE_TEMPLATE/submit_question.md

Co-Authored-By: Jeremy Schendel <[email protected]>

TomAugspurger

Looks great!

jreback · 2020-04-03T19:43:19Z

thanks @MomIsBestFriend

jreback · 2020-04-03T19:44:40Z

it even pre-sets some labels, nice!

ADMIN: Create separate issue templates for different usecases

c06f29c

ShaharNaveh added the Admin Administrative tasks related to the pandas project label Mar 31, 2020

Merge two documentation templates

1a3b03d

mroeschke reviewed Mar 31, 2020

View reviewed changes

TomAugspurger reviewed Mar 31, 2020

View reviewed changes

MomIsBestFriend added 8 commits April 1, 2020 11:49

Merge remote-tracking branch 'upstream/master' into issue-template

cb13d8e

Moved guide for minimial example before the Code sample section

3956ae1

XREF: pandas-dev#33187 (comment)

Using checkboxes in the bug report

68a8cbc

XREF: pandas-dev#33187 (comment)

Newline nits

61fdf40

Encouraging users to supply URL of problematic documentation

fe66538

Renamed "wrong_or_missing_documentation" to "documentation_improvement"

b9ead18

Encouraging users to write a docstring for desired feature

7f5ae95

XREF: pandas-dev#33187 (comment)

Added "API breaking implications" header

7fb0a81

XREF: pandas-dev#33187 (comment)

ShaharNaveh commented Apr 1, 2020

View reviewed changes

.github/ISSUE_TEMPLATE/submit_question.md Outdated Show resolved Hide resolved

ShaharNaveh commented Apr 1, 2020

View reviewed changes

.github/ISSUE_TEMPLATE/feature_request.md Show resolved Hide resolved

jorisvandenbossche reviewed Apr 1, 2020

View reviewed changes

.github/ISSUE_TEMPLATE/bug_report.md Outdated Show resolved Hide resolved

.github/ISSUE_TEMPLATE/documentation_improvement.md Outdated Show resolved Hide resolved

ShaharNaveh and others added 2 commits April 1, 2020 15:40

Update .github/ISSUE_TEMPLATE/bug_report.md

3ac643e

Co-Authored-By: Tom Augspurger <[email protected]>

Update .github/ISSUE_TEMPLATE/documentation_improvement.md

cd4565a

Co-Authored-By: Joris Van den Bossche <[email protected]>

mroeschke reviewed Apr 1, 2020

View reviewed changes

.github/ISSUE_TEMPLATE/bug_report.md Outdated Show resolved Hide resolved

mroeschke reviewed Apr 1, 2020

View reviewed changes

.github/ISSUE_TEMPLATE/bug_report.md Outdated Show resolved Hide resolved

mroeschke reviewed Apr 1, 2020

View reviewed changes

MomIsBestFriend added 6 commits April 1, 2020 19:16

Replaced notes with checkboxes

ebbf55e

XREF: pandas-dev#33187 (comment)

Fixed typos/grammer mistakes

842f8da

XREF: pandas-dev#33187 (comment) pandas-dev#33187 (comment)

Merge remote-tracking branch 'upstream/master' into issue-template

413d30a

Add labels to each issue template

8c891f3

Added "Needs Triage" label to all templates

9bf7738

Merge remote-tracking branch 'upstream/master' into issue-template

d7cbd30

jschendel reviewed Apr 2, 2020

View reviewed changes

.github/ISSUE_TEMPLATE/submit_question.md Outdated Show resolved Hide resolved

.github/ISSUE_TEMPLATE/submit_question.md Outdated Show resolved Hide resolved

ShaharNaveh and others added 3 commits April 2, 2020 03:08

Update .github/ISSUE_TEMPLATE/submit_question.md

5f9040c

Co-Authored-By: Jeremy Schendel <[email protected]>

Update .github/ISSUE_TEMPLATE/submit_question.md

3fb35c4

Co-Authored-By: Jeremy Schendel <[email protected]>

Merge remote-tracking branch 'upstream/master' into issue-template

72ccc0f

TomAugspurger approved these changes Apr 3, 2020

View reviewed changes

jreback added this to the 1.1 milestone Apr 3, 2020

jreback merged commit b712971 into pandas-dev:master Apr 3, 2020

ShaharNaveh deleted the issue-template branch April 6, 2020 08:24


		#### Location of the documentation

		[this should provide a description of what documentation you believe needs to be fixed/improved]


		#### Describe the solution you'd like

		[this should provide a description of the feature request, e.g. "`DataFrame.foo` should get a new parameter `bar` that [...]"]

Uh oh!

ADMIN: Create separate issue templates for different usecases #33187

ADMIN: Create separate issue templates for different usecases #33187

Uh oh!

Conversation

ShaharNaveh commented Mar 31, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mroeschke Mar 31, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomAugspurger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaharNaveh Apr 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

TomAugspurger left a comment

Choose a reason for hiding this comment

Uh oh!

jreback commented Apr 3, 2020

Uh oh!

jreback commented Apr 3, 2020

Uh oh!

Uh oh!

mroeschke Mar 31, 2020 •

edited

Loading

ShaharNaveh Apr 1, 2020 •

edited

Loading