Enhancement: Make issue templates more readily accessible #6644 #6647

wkurniawan07 · 2017-02-20T19:04:06Z

Outline of Solution

Moved the templates to .github folder
Added direct links from issue tracker
Made the contents of the templates directly copy-and-paste-able.

@samsontmr some of the changes here are contradicting what we've done in #6351, really sorry for that but as it turns out things don't always work the way we planned it to be, do they?

samsontmr · 2017-02-21T00:41:45Z

.github/CONTRIBUTING.md

+* For feature/enhancement requests, refer [here](template-featureRequest.md).
+* For new contributor introduction, refer [here](template-contributorIntro.md).
+* For help requests, refer [here](template-helpRequest.md).
+* For other works like refactoring or updating documentation, simply provide a clear issue title and description of the work to be done.


works -> work

samsontmr · 2017-02-21T12:23:49Z

.github/template-featureRequest.md


-> Let us know if there already are similar features in TEAMMATES, and why they fall short of your expectations
+
+**Is the proposed feature/enhancement for the benefit of developers or users?**


"Will the proposed feature/enhancement benefit the developers or users?" sounds better.

samsontmr · 2017-02-21T12:24:23Z

.github/template-helpRequest.md


-> Tell us what you were trying to to / what you need help with
+**Provide us with more relevant information, such as screenshot, error stack traces, or console messages.**


screenshot -> screenshots

bump
EDIT: oops my previous comment didn't appear here. screenshot -> screenshots

samsontmr · 2017-02-21T12:25:46Z

.github/CONTRIBUTING.md

+* For feature/enhancement requests, refer [here](template-featureRequest.md).
+* For new contributor introduction, refer [here](template-contributorIntro.md).
+* For help requests, refer [here](template-helpRequest.md).
+* For other works like refactoring or updating documentation, simply provide a clear issue title and description of the works to be done.


works -> work
In this context, the singular "work" should still be used even though it might be referring to multiple subjects.

samsontmr · 2017-02-21T12:28:33Z

.github/template-bugReport.md

@@ -0,0 +1,18 @@
+**Issue Title:** Bug: [brief description of bug]
+
+Copy-and-paste the following content to the issue tracker and fill in with relevant details:


...the following template...and fill it in...

samsontmr · 2017-02-21T12:29:57Z

.github/template-bugReport.md

+
+Copy-and-paste the following content to the issue tracker and fill in with relevant details:
+```markdown
+**Tell us what environment you encountered the bug on, e.g. live server at `V5.93`, `master` branch at commit 1234567.**


Tell us what environment you encountered the bug on (e.g. live server at V5.93, master branch at commit 1234567)

Suggest formatting it in this way.

samsontmr · 2017-02-21T12:30:26Z

.github/template-featureRequest.md

@@ -0,0 +1,18 @@
+**Issue Title:** Feature: [your request in a line] OR Enhancement: [your suggestion in a line]
+
+Copy-and-paste the following content to the issue tracker and fill in with relevant details:


samsontmr · 2017-02-21T12:31:18Z

.github/template-contributorIntro.md

+
+
+
+**Tell us your real name and give a short self-introduction, e.g. your education background, why you want to contribute to TEAMMATES, etc.**


Tell us your real name and give a short self-introduction (e.g. your education background, why you want to contribute to TEAMMATES, etc)

Suggest formatting it in this way.

samsontmr · 2017-02-21T12:33:10Z

.github/template-featureRequest.md

+
+
+
+**Is the proposed feature/enhancement for the benefit of developers or users?**


Will the proposed feature/enhancement benefit the developers or users? sounds better.

samsontmr · 2017-02-21T12:34:31Z

.github/template-contributorIntro.md

@@ -0,0 +1,13 @@
+**Issue Title:** New Contributor Self-Intro [your real name]


New Contributor Self-Intro: [your real name]?

samsontmr · 2017-02-21T12:37:23Z

.github/template-contributorIntro.md

+- **Link to your app:** e.g. https://teammates-username.appspot.com
+- **Link to your fork:** e.g. https://github.com/username/teammates
+
+**Post a screenshot of changes you did (as seen on the UI).**


...changes you made... sounds better

samsontmr

Reading through the templates again, I have a suggestion: consider removing "Tell us" if the headers will be present in the actual issue they create; the headers should make sense as headers for their content. "Tell us" seems more like instructions on what the user is supposed to do and doesn't seem like it should appear in the headers? Thoughts?

samsontmr · 2017-02-21T14:33:52Z

.github/template-helpRequest.md


-> Tell us what you were trying to to / what you need help with
+**Provide us with more relevant information, such as screenshot, error stack traces, or console messages.**


bump
EDIT: oops my previous comment didn't appear here. screenshot -> screenshots

wkurniawan07 · 2017-02-21T15:10:33Z

@samsontmr you might have a point. I'll try going down that path and we can see if it's better.

wkurniawan07 · 2017-02-23T17:28:50Z

@samsontmr I tried to make it look more header-like. Can review again.

samsontmr

LGTM

damithc

Perhaps we can shorten the titles by moving some text into instructional comments? e.g.

**More info:**
<!-- give here more information such as screenshots, error stack traces, or console messages -->

Perhaps instructional comments can be phrased as instructions from us to the poster (see above example) while the headings are phrased as coming from poster? e.g. My name

What do you think?

damithc · 2017-02-24T04:41:25Z

.github/template-bugReport.md

+
+
+
+**Steps to reproduce the bug**


Use : everywhere, for consistency?

Why is it for consistency reason? There is no : anywhere in all template headings.

Add: I realize it was referring to Link to your app and similar, but those are one-liner info, not headings.

True. It's fine then.

damithc · 2017-02-24T04:43:02Z

.github/template-featureRequest.md

+
+
+
+**The party (developers/users) who will benefit from the proposed feature/enhancement**


Do we really need this?

This is good enough?

**Suggested enhancement:**  **Justification:** 

This reduces the clutter in the docs/ folder since the templates are meant to be used only in GitHub issue tracker.

In particular, ISSUE_TEMPLATE now links the template exactly instead of referring to CONTRIBUTING

1. Shortened the prefixes for fix-able issues 2. Converted the content so that they can be copy-pasted verbatim to the issue tracker (without the need to be displayed raw) 3. Made the content header-like instead of question-like or instruction-like

wkurniawan07 added the s.ToReview The PR is waiting for review(s) label Feb 20, 2017

wkurniawan07 assigned samsontmr Feb 20, 2017

samsontmr requested changes Feb 21, 2017

View reviewed changes

wkurniawan07 force-pushed the 6644-issue-templates-accessible branch from 05eee31 to 2658b44 Compare February 21, 2017 04:46

wkurniawan07 requested a review from samsontmr February 21, 2017 05:19

samsontmr requested changes Feb 21, 2017

View reviewed changes

wkurniawan07 force-pushed the 6644-issue-templates-accessible branch from 2658b44 to fa1ff9a Compare February 21, 2017 14:23

wkurniawan07 requested a review from samsontmr February 21, 2017 14:23

samsontmr requested changes Feb 21, 2017

View reviewed changes

wkurniawan07 force-pushed the 6644-issue-templates-accessible branch 3 times, most recently from b205d53 to 19f57b2 Compare February 23, 2017 17:27

wkurniawan07 requested a review from samsontmr February 23, 2017 17:28

samsontmr approved these changes Feb 24, 2017

View reviewed changes

wkurniawan07 requested a review from damithc February 24, 2017 04:27

damithc requested changes Feb 24, 2017

View reviewed changes

wkurniawan07 added 4 commits February 24, 2017 13:44

move all the templates to .github folder

e0e7087

This reduces the clutter in the docs/ folder since the templates are meant to be used only in GitHub issue tracker.

switch bug report and feature request in CONTRIBUTING.md

72a3a30

improve phrasing in CONTRIBUTING and ISSUE_TEMPLATE

c7d086a

In particular, ISSUE_TEMPLATE now links the template exactly instead of referring to CONTRIBUTING

improve the issue templates

d715b45

1. Shortened the prefixes for fix-able issues 2. Converted the content so that they can be copy-pasted verbatim to the issue tracker (without the need to be displayed raw) 3. Made the content header-like instead of question-like or instruction-like

wkurniawan07 force-pushed the 6644-issue-templates-accessible branch from 19f57b2 to d715b45 Compare February 24, 2017 05:58

wkurniawan07 requested a review from damithc February 24, 2017 07:23

damithc approved these changes Feb 24, 2017

View reviewed changes

damithc added s.ToMerge The PR is approved by all reviewers including final reviewer; ready for merging and removed s.ToReview The PR is waiting for review(s) labels Feb 24, 2017

wkurniawan07 merged commit b2f63c2 into master Feb 24, 2017

wkurniawan07 deleted the 6644-issue-templates-accessible branch February 24, 2017 07:51

wkurniawan07 added this to the V5.97 milestone Feb 28, 2017

wkurniawan07 added the e.1 label Mar 1, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhancement: Make issue templates more readily accessible #6644 #6647

Enhancement: Make issue templates more readily accessible #6644 #6647

wkurniawan07 commented Feb 20, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017 •

edited

Loading

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr Feb 21, 2017

samsontmr left a comment

samsontmr Feb 21, 2017 •

edited

Loading

wkurniawan07 commented Feb 21, 2017

wkurniawan07 commented Feb 23, 2017

samsontmr left a comment

damithc left a comment

damithc Feb 24, 2017

wkurniawan07 Feb 24, 2017 •

edited

Loading

damithc Feb 24, 2017

damithc Feb 24, 2017

damithc Feb 24, 2017


		> Let us know if there already are similar features in TEAMMATES, and why they fall short of your expectations

		Is the proposed feature/enhancement for the benefit of developers or users?


		> Tell us what you were trying to to / what you need help with
		Provide us with more relevant information, such as screenshot, error stack traces, or console messages.

		@@ -0,0 +1,18 @@
		Issue Title: Bug: [brief description of bug]

		Copy-and-paste the following content to the issue tracker and fill in with relevant details:

		@@ -0,0 +1,18 @@
		Issue Title: Feature: [your request in a line] OR Enhancement: [your suggestion in a line]

		Copy-and-paste the following content to the issue tracker and fill in with relevant details:




		Tell us your real name and give a short self-introduction, e.g. your education background, why you want to contribute to TEAMMATES, etc.

		@@ -0,0 +1,13 @@
		Issue Title: New Contributor Self-Intro [your real name]




		The party (developers/users) who will benefit from the proposed feature/enhancement

Enhancement: Make issue templates more readily accessible #6644 #6647

Enhancement: Make issue templates more readily accessible #6644 #6647

Conversation

wkurniawan07 commented Feb 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samsontmr Feb 21, 2017 • 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samsontmr left a comment

Choose a reason for hiding this comment

samsontmr Feb 21, 2017 • edited Loading

Choose a reason for hiding this comment

wkurniawan07 commented Feb 21, 2017

wkurniawan07 commented Feb 23, 2017

samsontmr left a comment

Choose a reason for hiding this comment

damithc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wkurniawan07 Feb 24, 2017 • 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

samsontmr Feb 21, 2017 •

edited

Loading

samsontmr Feb 21, 2017 •

edited

Loading

wkurniawan07 Feb 24, 2017 •

edited

Loading