Further work on Github usability (issue templates) #5542

Merged
merged 1 commit into from Jan 3, 2017

Projects

None yet

4 participants

@gmelikov
Member
gmelikov commented Dec 30, 2016 edited

Description

This PR is a continuation of improving reporting templates and Github-related documentation (#5361).

Changes - make issue template more obvious about importance to search our issue tracker first, and wrap logs appropriately.

Feel free to add your suggestions. I'll add them to this PR.

Motivation and Context

Make work on issues easier.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Performance enhancement (non-breaking change which improves efficiency)
  • Code cleanup (non-breaking change which makes code smaller or more readable)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • My code follows the ZFS on Linux code style requirements.
  • I have updated the documentation accordingly.
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes.
  • All new and existing tests passed.
  • Change has been approved by a ZFS on Linux member.
@gmelikov
Member

There is #5529 PR, where @mailinglists35 added more info about logs mark, but i think it may be too tricky to have large piece of different methods.

Unfourtunately, there'll always be someone who won't read them =(

.github/ISSUE_TEMPLATE.md
@@ -1,9 +1,13 @@
<!--
Thank you for reporting an issue.
+*IMPORTANT* - please search our issue tracker *first* to ensure the
@dinatale2
dinatale2 Dec 31, 2016 Member

Please search our issue tracker *before* making a new issue. If you cannot find a similar issue, then create a new issue.

@mailinglists35
mailinglists35 Dec 31, 2016

imo the message that should reach the user when reporting a bug is that if he is confident has found unexpected behaviour of zfs should first search if someone else already reported it.

the link to how to search issues on github should be provided: https://help.github.com/articles/searching-issues/

some other issue reporting guidelines:
media player classic homecinema https://trac.mpc-hc.org/wiki/How_to_Report_Issues
some random google result for 'how to report issues' http://aslain.com/index.php?/topic/9-how-to-report-a-bug-or-issue/
drupal: https://www.drupal.org/node/73179

@dinatale2
dinatale2 Dec 31, 2016 Member

We could always point them to our contributing guidelines.

@gmelikov
gmelikov Dec 31, 2016 Member

We already have Please review the guidelines for contributing to this repository. message on top of new issue page. @dinatale2 agree with you.

.github/ISSUE_TEMPLATE.md
This issue tracker is for bugs and issues only.
-If you need general support please use
-our mailing list. https://github.com/zfsonlinux/zfs/wiki/Mailing-Lists
+If you need general support please use our mailing list.
@dinatale2
dinatale2 Dec 31, 2016 Member

If you need general support, please use our mailing list.

@mailinglists35
mailinglists35 Dec 31, 2016

also, this can be said as "if you want to ask a question or are not sure why is zfs not behaving like you are expecting, please use the mailing list". "general support" is not that descriptive to new users.

@mailinglists35
mailinglists35 Dec 31, 2016

also, user should be directed to docs+wiki first, then search the mailing lists before being encouraged to write to list

@mailinglists35
mailinglists35 Dec 31, 2016

so tell sometihing meaning "please search and read the wiki and mailing lists archives and only if you don't find ask on lists"

@dinatale2
dinatale2 Dec 31, 2016 Member

@mailinglists35 I like your suggestion about referring to documentation/wiki. We should likely add a bit about that in the contributing guidelines.

.github/ISSUE_TEMPLATE.md
@@ -30,6 +34,9 @@ modinfo spl | grep -iw version
### Include any warning/errors/backtraces from the system logs
<!--
+*IMPORTANT* - You should mark logs (see example below),
+otherwise Github will mess them up.
@dinatale2
dinatale2 Dec 31, 2016 Member

*IMPORTANT* - Please mark logs or Github will not display them correctly. An example is provided below.?

@gmelikov
Member

@dinatale2 thanks, added your fixes.

@mailinglists35 thanks, your suggestions added too.

.github/ISSUE_TEMPLATE.md
@@ -30,6 +35,9 @@ modinfo spl | grep -iw version
### Include any warning/errors/backtraces from the system logs
<!--
+*IMPORTANT* - Please mark logs or Github will not display them correctly.
@mailinglists35
mailinglists35 Dec 31, 2016 edited

suggestion: "mark logs and text output from terminal commands or else Github [...]"

@gmelikov
gmelikov Dec 31, 2016 Member

Maybe you're right, but i think it's obvious enough with logs only.

Maybe it's better to add this info to header?
### Include any warning/errors/backtraces from the system logs or commands output

@dinatale2
dinatale2 Dec 31, 2016 Member

@gmelikov I think what @mailinglists35 suggested is sufficient.

.github/ISSUE_TEMPLATE.md
+
+*IMPORTANT* - This issue tracker is for *bugs* and *issues* only.
+Please search the wiki and mailing lists archives
+and only if you don't find ask on mailing list.
@behlendorf
behlendorf Dec 31, 2016 Member

This last sentence isn't clear. I believe you mean s/if you don't find ask/if you don't find an answer ask/

@gmelikov
Member
gmelikov commented Jan 1, 2017

All requested changes were made, thanks.

.github/ISSUE_TEMPLATE.md
+
+*IMPORTANT* - This issue tracker is for *bugs* and *issues* only.
+Please search the wiki and mailing lists archives
+and only if you don't find an answer ask on mailing list.
@dinatale2
dinatale2 Jan 2, 2017 Member

Please search the wiki and the mailing list archives before asking questions on the mailing list.?

@gmelikov
gmelikov Jan 2, 2017 Member

Thanks, Fixed.

.github/ISSUE_TEMPLATE.md
+https://github.com/zfsonlinux/zfs/issues
+
+*IMPORTANT* - This issue tracker is for *bugs* and *issues* only.
+Please search the wiki and the mailing list archives before asking questions on the mailing list.
@dinatale2
dinatale2 Jan 2, 2017 Member

Please wrap this line because it is over 80 characters long.

@gmelikov gmelikov Further work on Github usability (issue templates)
669f6b0
@behlendorf behlendorf merged commit 42b64e5 into zfsonlinux:master Jan 3, 2017

15 of 23 checks passed

buildbot/Amazon 2015.09 x86_64 Release (TEST) Build done.
Details
buildbot/CentOS 6.7 x86_64 (TEST) Build done.
Details
buildbot/CentOS 7 x86_64 Mainline (TEST) Build done.
Details
buildbot/Kernel.org Built-in x86_64 (BUILD) Build done.
Details
buildbot/Kernel.org Default x86_64 (BUILD) Build done.
Details
buildbot/Ubuntu 14.04 x86_64 (TEST) Build done.
Details
buildbot/Ubuntu 14.04 i686 (TEST) Build started.
Details
buildbot/Ubuntu 16.04 x86_64 Kmemleak (TEST) Build started.
Details
buildbot/Amazon 2015.09 x86_64 (BUILD) Build done.
Details
buildbot/Amazon 2015.09 x86_64 (STYLE) Build done.
Details
buildbot/Amazon 2015.09 x86_64 SIMD (TEST) Build done.
Details
buildbot/CentOS 6.7 x86_64 (BUILD) Build done.
Details
buildbot/CentOS 7.1 x86_64 (BUILD) Build done.
Details
buildbot/CentOS 7.1 x86_64 (TEST) Build done.
Details
buildbot/Debian 8 arm (BUILD) Build done.
Details
buildbot/Debian 8 ppc (BUILD) Build done.
Details
buildbot/Debian 8 ppc64 (BUILD) Build done.
Details
buildbot/Debian 8 x86_64 (BUILD) Build done.
Details
buildbot/Fedora 24 x86_64 (BUILD) Build done.
Details
buildbot/Ubuntu 14.04 i686 (BUILD) Build done.
Details
buildbot/Ubuntu 14.04 x86_64 (BUILD) Build done.
Details
buildbot/Ubuntu 16.04 aarch64 (BUILD) Build done.
Details
buildbot/Ubuntu 16.04 x86_64 (BUILD) Build done.
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment