docs: Use GitHub Issue forms as Issue templates #1576

matthewfeickert · 2021-09-01T07:42:46Z

Description

Resolves #1452

Add GitHub Issue forms to provide better context and guide users. As the forms can also require information to be entered before the Issue can be created, they can also streamline input from users.

These Issue forms are heavily influenced / copied from Ansible's (thanks @webknjaz!).

Checklist Before Requesting Reviewer

Tests are passing
"WIP" removed from the title of the pull request
Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

Summarize commit messages into a comprehensive review of the PR

* Use GitHub Issue form Issue templates to provide more consistent context of requested information from users
   - c.f. 
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms
   - Remove all previous GitHub Issue templates
   - These Issue forms are heavily influenced / copied from Ansible's https://github.com/ansible/ansible/
   - Intentionally add a second space after emojis to have them render better on macOS
* Add config.yml to also link users to GitHub Discussions, the pyhf tutorial, and the Code of Conduct

Co-authored-by: Sviatoslav Sydorenko <[email protected]>

codecov · 2021-09-01T07:43:33Z

Codecov Report

Merging #1576 (209daad) into master (80a27ac) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1576   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          63       63           
  Lines        4050     4050           
  Branches      576      576           
=======================================
  Hits         3957     3957           
  Misses         54       54           
  Partials       39       39

Flag	Coverage Δ
contrib	`25.43% <ø> (ø)`
unittests	`97.48% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 80a27ac...209daad. Read the comment docs.

matthewfeickert · 2021-09-01T07:45:21Z

As there is no good way to preview these in a PR, I did all the writing on my fork https://github.com/matthewfeickert/pyhf. I'd invite everyone to go over to my fork's Issues to review the PR.

@alexander-held as you open some of the best Issues on pyhf if we can get your review on what parts of this are good and what parts might slow you down / be obnoxious that would be really helpful!

@kratsg @lukasheinrich Once this is in (I wanted to mention new Issues in the release email) I'll start up the release checklist to release v0.6.3. 👍

.github/ISSUE_TEMPLATE/bug-report.yml

.github/ISSUE_TEMPLATE/feature-request.yml

alexander-held

The templates look very good to me. I have a few rather minor comments. Is there still the possibility to upload files (e.g. a workspace) in the new bug report form? I spontaneously would not know how to do it.

.github/ISSUE_TEMPLATE/config.yml

alexander-held · 2021-09-01T14:22:05Z

.github/ISSUE_TEMPLATE/bug-report.yml

+      Paste verbatim output from `pyhf --version` below, under
+      the prompt line. Please don't wrap it with tripple backticks &mdash; your
+      whole input will be turned into a code snippet automatically.


I am assuming that users with editable installs who checkout different versions of pyhf will generally understand the system enough so that this is not an issue, but in principle the output of pyhf --version may not match the actual version in use (this is for example the case for me right now).

@alexander-held You just saying that if you are locally installing pyhf and not using a supported release from PyPI then you might get something like

$ pyhf --version pyhf, version 0.6.3.dev17

? Or do you mean something in addition to this?

I mean something closely related, yes. I won't get the dev tags if I clone the repo, check out tag v0.6.2, pip install -e ., and then check out the master branch. pyhf --version will show pyhf, version 0.6.2 nevertheless, even though I am using a newer version. This is so minor though that it is probably not worth any changes.

Ah gotcha yeah. 👍 I think this is probably okay, as you're like our ultimate power user and you know what you're doing here. I'm more assuming that people who are reporting bugs are installing directly from PyPI.

Though I'll mention here that when you report bugs in the future feel free to just give whatever information is the most relevant here (e.g. git commit hash) or something.

alexander-held · 2021-09-01T14:23:07Z

.github/ISSUE_TEMPLATE/bug-report.yml

+
+- type: textarea
+  attributes:
+    label: pyhf Version


Would suggest moving this towards the end of the form, in my experience with existing issues the version seems to rarely matter a lot.

alexander-held · 2021-09-01T14:24:41Z

.github/ISSUE_TEMPLATE/bug-report.yml

+  attributes:
+    label: OS / Environment
+    description: >-
+      Provide the name of your operating system and the output of `uname --all`.


This part seems like it would not matter for the large majority of existing issues. I think it does not hurt to have for completeness, but would suggest moving to the end of the fields. uname --all will not always work, for example on Mac OS I need uname -a.

alexander-held · 2021-09-01T14:25:42Z

.github/ISSUE_TEMPLATE/bug-report.yml

+
+      **HINT:** You can paste [GitHub Gist](https://gist.github.com) links for larger files.
+    value: |
+      <!--- Paste your minimal failing Python example code between the quotes below -->


Maybe easier to use if the comment is above the cell, and the whole cell is python formatted? Not clear to me why this different style is used here.

Probably to give people a chance to also add text, not just code.

Good point. I assumed extra text could go into summary / expected results / actual results, but for more complicated setups the opportunity for more text seems useful.

You could have two separate fields for code and text, of course. But then, you can never guess how many code blocks the reporter would need.

You could have two separate fields for code and text, of course. But then, you can never guess how many code blocks the reporter would need.

Yeah. I think I may stick with doing the hint and then just adding an optional place for people to upload a workspace file. This way I don't have to have both an entry for CLI and for Python APIs.

webknjaz · 2021-09-01T14:30:59Z

Is there still the possibility to upload files (e.g. a workspace) in the new bug report form?

Every textarea field is a separate WYSIWYG, just like the ones where you type in comments. So people can attach files/pictures there as usual.

matthewfeickert · 2021-09-02T01:07:37Z

Thanks for these comments! I think I've applied all of them now. 👍

.github/ISSUE_TEMPLATE/bug-report.yml

.github/ISSUE_TEMPLATE/config.yml

.github/ISSUE_TEMPLATE/documentation-report.yml

.github/ISSUE_TEMPLATE/feature-request.yml

.github/ISSUE_TEMPLATE/~release-checklist.md

.github/ISSUE_TEMPLATE/bug-report.yml

Thank you Sviatoslav! Co-authored-by: Sviatoslav Sydorenko <[email protected]>

* Fix the links in the Issue forms to point to the same Issue type label as the form * Amends PR #1576

matthewfeickert added docs Documentation related community Communication with users labels Sep 1, 2021

matthewfeickert self-assigned this Sep 1, 2021

matthewfeickert requested review from kratsg and lukasheinrich September 1, 2021 07:45

webknjaz reviewed Sep 1, 2021

View reviewed changes

.github/ISSUE_TEMPLATE/bug-report.yml Show resolved Hide resolved

webknjaz reviewed Sep 1, 2021

View reviewed changes

.github/ISSUE_TEMPLATE/feature-request.yml Outdated Show resolved Hide resolved

alexander-held reviewed Sep 1, 2021

View reviewed changes

matthewfeickert force-pushed the docs/update-issue-templates branch from 3013ce9 to 8ed2171 Compare September 2, 2021 12:32

kratsg requested changes Sep 2, 2021

View reviewed changes

kratsg mentioned this pull request Sep 2, 2021

Provide pyhf debug utility that prints debugging information for user issues #1580

Open

matthewfeickert and others added 8 commits September 2, 2021 12:03

Use Ansible bug report template

00e8afd

Rename

20d0a1f

Copy over from fork

8e3fbb9

Capitalize Request for consistency

c7d499a

Fix typo

72fbe52

Thank you Sviatoslav! Co-authored-by: Sviatoslav Sydorenko <[email protected]>

Apply Alex's suggestions

d4def6b

Ask for example description

dbb6f35

Add space for render to look better on mac

209daad

matthewfeickert force-pushed the docs/update-issue-templates branch from d4a83aa to 209daad Compare September 2, 2021 17:03

matthewfeickert requested a review from kratsg September 2, 2021 17:04

kratsg approved these changes Sep 2, 2021

View reviewed changes

matthewfeickert merged commit 7bf6ed2 into master Sep 2, 2021

matthewfeickert deleted the docs/update-issue-templates branch September 2, 2021 18:23

matthewfeickert mentioned this pull request Sep 2, 2021

docs: Fix links to existing issues for 'docs' and 'feat' labels #1582

Merged

4 tasks

matthewfeickert added a commit that referenced this pull request Sep 2, 2021

docs: Fix links to existing issues for 'docs' and 'feat' labels (#1582)

c5b5c58

* Fix the links in the Issue forms to point to the same Issue type label as the form * Amends PR #1576

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Use GitHub Issue forms as Issue templates #1576

docs: Use GitHub Issue forms as Issue templates #1576

matthewfeickert commented Sep 1, 2021 •

edited

Loading

codecov bot commented Sep 1, 2021 •

edited

Loading

matthewfeickert commented Sep 1, 2021 •

edited

Loading

alexander-held left a comment

alexander-held Sep 1, 2021

matthewfeickert Sep 2, 2021

alexander-held Sep 2, 2021

matthewfeickert Sep 2, 2021

alexander-held Sep 1, 2021

alexander-held Sep 1, 2021

alexander-held Sep 1, 2021

webknjaz Sep 1, 2021

alexander-held Sep 1, 2021

webknjaz Sep 1, 2021

matthewfeickert Sep 2, 2021

webknjaz commented Sep 1, 2021

matthewfeickert commented Sep 2, 2021

docs: Use GitHub Issue forms as Issue templates #1576

docs: Use GitHub Issue forms as Issue templates #1576

Conversation

matthewfeickert commented Sep 1, 2021 • edited Loading

Description

Checklist Before Requesting Reviewer

Before Merging

codecov bot commented Sep 1, 2021 • edited Loading

Codecov Report

matthewfeickert commented Sep 1, 2021 • edited Loading

alexander-held left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz commented Sep 1, 2021

matthewfeickert commented Sep 2, 2021

matthewfeickert commented Sep 1, 2021 •

edited

Loading

codecov bot commented Sep 1, 2021 •

edited

Loading

matthewfeickert commented Sep 1, 2021 •

edited

Loading