docs: add new section to REPORTING-BUGS and github issue templates

- Add a section to REPORTING-BUGS to clarify what is required for a good
  GitHub issue
- Add a note to REPORTING-BUGS that questions should go to the mailing
  list
- Add a bug GitHub issue template that encourages people to read
  REPORTING-BUGS and include necessary information
- Add a GitHub issue enhancement template to try and set expectations
  reasonably
- Add a SUPPORT.md file because GitHub seems to link to it when a
  reporter first makes an issue

Signed-off-by: Sitsofe Wheeler <sitsofe@yahoo.com>

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
new file mode 100644 (file)
index 0000000..272968f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,5 @@
+**Please acknowledge you have done the following before creating a ticket**
+
+- [ ] I have read the GitHub issues section of [REPORTING-BUGS](../blob/master/REPORTING-BUGS).
+
+<!-- replace me with bug report / enhancement request -->

diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
new file mode 100644 (file)
index 0000000..1073816
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -0,0 +1,20 @@
+---
+name: Report a bug
+about: For bugs that are reproducible with the latest fio releases
+
+---
+
+**Please acknowledge the following before creating a ticket**
+
+- [ ] I have read the GitHub issues section of [REPORTING-BUGS](../blob/master/REPORTING-BUGS).
+
+**Description of the bug:**
+<!--replaceme-->
+
+**Environment**: <!-- Name and version of operating system -->
+
+**fio version**: <!--replaceme-->
+
+**Reproduction steps**
+<!-- Please minimise the job file/command line options down to only those
+necessary to reproduce the issue (https://stackoverflow.com/help/mcve ) -->

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644 (file)
index 0000000..c7e3b37
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,6 @@
+blank_issues_enabled: true
+
+contact_links:
+- name: General questions (e.g. "How do I...", "Why is...") that are related to fio
+  url: http://vger.kernel.org/vger-lists.html#fio
+  about: Please send questions to the fio mailing list (plain-text emails ONLY)

diff --git a/.github/ISSUE_TEMPLATE/enhancement.md b/.github/ISSUE_TEMPLATE/enhancement.md
new file mode 100644 (file)
index 0000000..1d4ba77
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/enhancement.md
@@ -0,0 +1,11 @@
+---
+name: Feature enhancement request
+about: Suggest a new fio feature
+labels: enhancement
+
+---
+
+**Description of the new feature**
+<!-- Please be aware regular fio developers are busy with non-fio work. Because
+of this, most requests are only completed if someone from outside the project
+contributes the code. -->

diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md
new file mode 100644 (file)
index 0000000..8d9df86
--- /dev/null
+++ b/.github/SUPPORT.md
@@ -0,0 +1,36 @@
+# Getting support for fio
+
+## General questions
+
+Please use the fio mailing list for asking general fio questions (e.g. "How do
+I do X?", "Why does Y happen?"). See the Mailing list section of the
+[README][readme] for details).
+
+## Reporting bugs
+
+As mentioned in [REPORTING-BUGS][reportingbugs], fio bugs and enhancements can
+be reported to the fio mailing list or fio's GitHub issues tracker.
+
+When reporting bugs please include ALL of the following:
+- Description of the issue
+- fio version number tested. If your fio isn't among the recent releases (see
+  the [fio releases page][releases]) please build a new one from source (see
+  the Source and Building sections of the [README][readme] for how to do this)
+  and reproduce the issue with the fresh build before filing an issue.
+- Reproduction steps and minimal job file/command line parameters.
+
+When requesting an enhancement only the description is needed.
+
+### GitHub issues specific information
+
+[Formatting terminal output with markdown][quotingcode] will help people who
+are reading your report. However, if the output is large (e.g. over 15 lines
+long) please consider including it as a text attachment. Avoid attaching
+pictures of screenshots as these are not searchable/selectable.
+
+<!-- Definitions -->
+
+[readme]: ../README
+[reportingbugs]: ../REPORTING-BUGS
+[releases]: ../../../releases
+[quotingcode]: https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax#quoting-code

diff --git a/REPORTING-BUGS b/REPORTING-BUGS
index 327b6caa0889d0671c95f192200c76db6aec62d4..c0204d7e09be4acb68b71b53112fe82a8e179852 100644 (file)
--- a/REPORTING-BUGS
+++ b/REPORTING-BUGS
@@ -1,16 +1,20 @@
 Reporting a bug
 ---------------
 
-If you notice anything that seems like a fio bug, please do send email
-to the list (fio@vger.kernel.org, see README) about it. If you are not
-running the newest release of fio, upgrading first is recommended.
+...via the mailing list
+=======================
+
+If you notice anything that seems like a fio bug or want to ask fio related
+questions, please send a plain-text only email to the list
+(fio@vger.kernel.org, see README) about it. If you are not running the newest
+release of fio please upgrade first.
 
 When reporting a bug, you'll need to include:
 
 1) A description of what you think the bug is
-2) Environment (Linux distro version, kernel version). This is mostly
+2) Environment (e.g. Linux distro version, kernel version). This is mostly
    needed if it's a build bug.
-3) The output from fio --version.
+3) The output from fio --version .
 4) How to reproduce. Please include a full list of the parameters
    passed to fio and the job file used (if any).
 
@@ -19,3 +23,20 @@ is left out and has to be asked for will add to the turn-around time
 of getting to the bottom of the issue, and an eventual fix.
 
 That's it!
+
+...via GitHub issues
+====================
+
+Please create an issue in the GitHub issue tracker
+(https://github.com/axboe/fio/issues ) but observe the following:
+
+a) If you are asking a question on how to do something ("How do I/Why is?")
+   please send it to the mailing list and not GitHub issues. The fio project
+   uses GitHub issues for reproducible bugs/enhancement requests.
+b) Please reproduce your bug using the latest fio listed on
+   https://github.com/axboe/fio/releases (see the Source and Building sections
+   of the README for how to build fio from source).
+c) Include all of the information requested in the mailing list section above
+   (description, environment, version, reproduction steps and all job parameters).
+
+Thanks!