Simplify standard issue templates #11

hillaryj · 2020-12-23T16:42:57Z

🗣 Description

Removes existing unused issue templates and creates some more catch-all ones.

Updates each of the descriptions to provide a buffet of choices to funnel users into creating the right kind of issue.

💭 Motivation and Context

Several issue types are unused, so we've tailored these to be more useful.

Closes #5.

🧪 Testing

Documentation-only changes; view the file to see the new setup.

✅ Checklist

This PR has an informative and human-readable title.
Changes are limited to a single goal - eschew scope creep!
All relevant type-of-change labels have been added.
I have read the CONTRIBUTING document.
These code changes follow cisagov code standards.
All relevant repo and/or project documentation has been updated
to reflect the changes in this PR.

jsf9k

Some formatting suggestions.

.github/ISSUE_TEMPLATE/bug.md

.github/ISSUE_TEMPLATE/epic.md

.github/ISSUE_TEMPLATE/issue.md

.github/ISSUE_TEMPLATE/question.md

Co-authored-by: Shane Frasier <[email protected]>

jsf9k

More minor thangs, plus some hate directed at the "Pitch" sections.

Also, I'm troubled by the fact that the epic and issue templates are almost identical. That would seem to indicate that they are the same type of thang, and maybe we should hide the difference from the end user. Just a thought.

.github/ISSUE_TEMPLATE/bug.md

jsf9k · 2020-12-23T17:31:34Z

.github/ISSUE_TEMPLATE/epic.md

+## Pitch ##
+
+Why does this feature belong in this project?
+
+This would be useful because...
+


I'm not opposed to removing this section, although I can see it being useful sometimes. Is there another name we could use for it?

The Pitch section basically duplicated the Motivation section that existed before - if you like that name better, we could switch.

Re "Pitch" vs "Motivation", I like the latter better. "Pitch" is less precise in my mind, and makes me think of salesmen.

What are you thoughts on the "Epic" and "Issue" templates being so similar? What if we reserved the right to create epics and only allowed external users to create issues?

My concern is that folks who are not @cisagov/team-ois are not going to know whether they should create an epic or an issue, and the answer will always be to create an issue. Why give them a confusing option that only makes sense for @cisagov/team-ois members? Unless I'm mistaken, there is no click-o-matic way to convert a mis-typed epic into an issue; it's a manual copy-and-paste process.

I think we should either:

Figure out how to clearly distinguish between the epic and issue templates, or

Drop the epic template as a template type

I assume we need epics in order to satisfy ZenHub. Is there more than one way to identify epics for Zenhub?

The "Pitch" vs "Motivation" part is resolved via commit d4bb29a, but I'd like to leave the "Epic" vs "Issue" open and hear from some other members of @cisagov/team-ois.

Also, is an epic issue type necessary for ZenHub?

As far as I can tell, the "epic" label is not required to exist in a GitHub repo in order for ZenHub to create epics in that repo (see Intro to ZenHub Epics). Although I don't know if ZenHub will automatically create an "epic" label in a repo if necessary- that would require a little bit of testing.

The Intro to ZenHub Epics has some good verbiage that we could use to help explain the difference between an issue and an epic.

Also, it's worth noting that ZenHub has functionality that allows one to convert issues to epics and vice versa.

As far as I can tell, the "epic" label is not required to exist in a GitHub repo in order for ZenHub to create epics in that repo

I'm talking about the "epic" issue type here, not labels.

They're such similar templates, I'd agree that it isn't necessary to duplicate. If someone wants to make an "epic" then they can just make a normal issue and tag it epic via labels or ZenHub.

Whoops, sorry about that. In that case, I don't think ZenHub matters here. I don't believe it cares about the GitHub issue type at all- it has it's own mechanism for determining if something is a ZenHub "issue" or "epic".

Eliminated in b31c613

.github/ISSUE_TEMPLATE/epic.md

.github/ISSUE_TEMPLATE/issue.md

Co-authored-by: Shane Frasier <[email protected]>

mcdonnnj

I didn't see any major hangups for me that weren't touched on by others. Thanks for taking this on to improve these.

.github/ISSUE_TEMPLATE/bug.md

.github/ISSUE_TEMPLATE/epic.md

mcdonnnj · 2020-12-29T20:15:02Z

.github/ISSUE_TEMPLATE/question.md

@@ -1,14 +1,29 @@
 ---
-name: 💬 Questions / Help
-about: If you have questions, please send us an Email
+name: 💬 Questions & Help


Just for visibility:
#5 (comment)

Addressed in 37b275b

Co-authored-by: Nick M. <[email protected]> Co-authored-by: Shane Frasier <[email protected]>

Add our top repositories and some guidance on how to get to documentation or ask questions instead of using issues.

jsf9k

This looks great to me. Thank you for sifting through my zillion suggestions.

hillaryj · 2021-01-04T18:37:47Z

I used the number of stars/forks of our repos to generate the list in QUESTIONS.md.

mcdonnnj

This is some strong work 💪. I did have one further piece of discussion regarding question.md, but it doesn't necessarily have to be resolved right now.

mcdonnnj · 2021-01-04T19:34:37Z

.github/ISSUE_TEMPLATE/question.md

@@ -5,25 +5,10 @@ about: If you have questions, visit GitHub Discussions and Wiki pages

 # 💬 Questions #


I think that rather than having a question.md template, we should add a config.yml to modify the Issue Selector like so:

--- # When we are comfortable with our templates, this should be changed to false # to force new issues into an existing template. blank_issues_enabled: true contact_links: - name: Questions url: https://github.com/cisagov/.github/QUESTIONS.md about: Please also see our documentation and Discussion boards for common questions and topics.

@dav3r @jsf9k I would appreciate your thoughts as well. You can see a sample of what it would look like in one of my testing repos here.

I do this... take a look at:
https://github.com/felddy/foundryvtt-docker/blob/develop/.github/ISSUE_TEMPLATE/config.yml

I like what @mcdonnnj and @felddy are suggesting.

I like the link to direct questions to the repo's GitHub Discussions, as @felddy has shown.

Looks good! We can use that yml approach to link directly to Discussions in certain repositories and to QUESTIONS.md for the default/generic. Unless there's a way to have it relatively-refer to the current repository's Discussions.

Looks good! We can use that yml approach to link directly to Discussions in certain repositories and to QUESTIONS.md for the default/generic. Unless there's a way to have it relatively-refer to the current repository's Discussions.

Would a relative link like this work?

Looks good! We can use that yml approach to link directly to Discussions in certain repositories and to QUESTIONS.md for the default/generic. Unless there's a way to have it relatively-refer to the current repository's Discussions.

Would a relative link like this work?

Already merged 😢

The problem I see with that is that not all repositories have Discussions or Wiki pages existent or active. QUESTIONS.md will at least give someone a starting point for the common repositories if they wander in.

Looks good! We can use that yml approach to link directly to Discussions in certain repositories and to QUESTIONS.md for the default/generic. Unless there's a way to have it relatively-refer to the current repository's Discussions.

Would a relative link like this work?

Remember that adding anything to ISSUE_TEMPLATE in a repository will break the automatic inclusion of these defaults. I had to manually add these issue templates to cisagov/cyhy_amis in cisagov/cyhy_amis#300 because of the monthly redeploy template we added.

I did not have success when testing a relative link in config.yml when I tried.

dav3r

This looks awesome to me - thanks @hillaryj for taking on this effort! 🎻

Update the templates to reflect the changes made in cisagov/.github#11

hillaryj added 2 commits December 23, 2020 11:23

Update question template to direct to wiki and discussion boards

6e435c6

Simplify templates

465d045

hillaryj added improvement This issue or pull request will add or improve functionality, maintainability, or ease of use documentation This issue or pull request improves or adds to documentation labels Dec 23, 2020

hillaryj requested review from jsf9k, dav3r and mcdonnnj December 23, 2020 16:42

hillaryj self-assigned this Dec 23, 2020

hillaryj requested a review from felddy as a code owner December 23, 2020 16:42

hillaryj added 3 commits December 23, 2020 11:49

Remove trailing whitespace

0d39abc

Fix EOF

db07de8

Sort keywords so specifics are first

116eb70

hillaryj changed the title ~~Improve and simplify standard issue templates~~ Simplify standard issue templates Dec 23, 2020

jsf9k reviewed Dec 23, 2020

View reviewed changes

Apply suggestions from code review

9bb9ac0

Co-authored-by: Shane Frasier <[email protected]>

jsf9k reviewed Dec 23, 2020

View reviewed changes

hillaryj and others added 3 commits December 28, 2020 09:30

Apply suggestions from code review

3985206

Co-authored-by: Shane Frasier <[email protected]>

Update titles and remove Pitch wording

d4bb29a

Update question.md

b9a7a55

mcdonnnj approved these changes Dec 29, 2020

View reviewed changes

hillaryj and others added 5 commits January 4, 2021 08:32

Apply suggestions from code review

4fa3422

Co-authored-by: Nick M. <[email protected]> Co-authored-by: Shane Frasier <[email protected]>

Combine epic type into regular issue

b31c613

Restore unordered list formatting

1af317d

Create QUESTIONS.md

5611c63

Add our top repositories and some guidance on how to get to documentation or ask questions instead of using issues.

Refer question issues to new QUESTIONS.md

37b275b

hillaryj requested review from jsf9k and mcdonnnj January 4, 2021 17:18

jsf9k approved these changes Jan 4, 2021

View reviewed changes

Add Sparrow link

1ebe67c

mcdonnnj approved these changes Jan 4, 2021

View reviewed changes

dav3r approved these changes Jan 5, 2021

View reviewed changes

Move questions to a config file link

402cf85

hillaryj merged commit 45aa08c into develop Jan 5, 2021

hillaryj deleted the improve-issue-templates branch January 5, 2021 16:50

jsf9k mentioned this pull request Jan 5, 2021

Fix QUESTIONS.md link in config #12

Merged

6 tasks

mcdonnnj added a commit to cisagov/cyhy_amis that referenced this pull request Jan 5, 2021

Update GitHub Issue templates

b547b25

Update the templates to reflect the changes made in cisagov/.github#11

mcdonnnj mentioned this pull request Jan 5, 2021

Update GitHub Issue templates cisagov/cyhy_amis#304

Open

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Simplify standard issue templates #11

Simplify standard issue templates #11

hillaryj commented Dec 23, 2020

jsf9k left a comment

jsf9k left a comment •

edited

Loading

jsf9k Dec 23, 2020

hillaryj Dec 23, 2020

jsf9k Dec 28, 2020

jsf9k Dec 28, 2020 •

edited

Loading

jsf9k Dec 29, 2020 •

edited

Loading

dav3r Dec 29, 2020

jsf9k Dec 29, 2020

hillaryj Dec 29, 2020

dav3r Dec 29, 2020

hillaryj Jan 4, 2021

mcdonnnj left a comment

mcdonnnj Dec 29, 2020

hillaryj Jan 4, 2021

jsf9k left a comment

hillaryj commented Jan 4, 2021

mcdonnnj left a comment

mcdonnnj Jan 4, 2021

felddy Jan 4, 2021

jsf9k Jan 4, 2021

dav3r Jan 5, 2021

hillaryj Jan 5, 2021

jsf9k Jan 5, 2021

jsf9k Jan 5, 2021

hillaryj Jan 5, 2021 •

edited

Loading

jsf9k Jan 5, 2021

mcdonnnj Jan 5, 2021

dav3r left a comment

		@@ -5,25 +5,10 @@ about: If you have questions, visit GitHub Discussions and Wiki pages

		# 💬 Questions #

Simplify standard issue templates #11

Simplify standard issue templates #11

Conversation

hillaryj commented Dec 23, 2020

🗣 Description

💭 Motivation and Context

🧪 Testing

✅ Checklist

jsf9k left a comment

Choose a reason for hiding this comment

jsf9k left a comment • edited Loading

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

jsf9k Dec 28, 2020 • edited Loading

Choose a reason for hiding this comment

jsf9k Dec 29, 2020 • edited Loading

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

mcdonnnj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jsf9k left a comment

Choose a reason for hiding this comment

hillaryj commented Jan 4, 2021

mcdonnnj 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

hillaryj Jan 5, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dav3r left a comment

Choose a reason for hiding this comment

jsf9k left a comment •

edited

Loading

jsf9k Dec 28, 2020 •

edited

Loading

jsf9k Dec 29, 2020 •

edited

Loading

hillaryj Jan 5, 2021 •

edited

Loading