From 96d1809bf977cb038db4f56e1c9f9d0951966fb4 Mon Sep 17 00:00:00 2001 From: Sitsofe Wheeler Date: Fri, 17 Feb 2017 07:09:12 +0000 Subject: [PATCH] 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 --- .github/ISSUE_TEMPLATE.md | 5 ++++ .github/ISSUE_TEMPLATE/bug-report.md | 20 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 6 +++++ .github/ISSUE_TEMPLATE/enhancement.md | 11 ++++++++ .github/SUPPORT.md | 36 +++++++++++++++++++++++++++ REPORTING-BUGS | 31 +++++++++++++++++++---- 6 files changed, 104 insertions(+), 5 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/ISSUE_TEMPLATE/bug-report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/enhancement.md create mode 100644 .github/SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..272968f8 --- /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). + + diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md new file mode 100644 index 00000000..10738165 --- /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:** + + +**Environment**: + +**fio version**: + +**Reproduction steps** + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..c7e3b372 --- /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 index 00000000..1d4ba77d --- /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** + diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 00000000..8d9df863 --- /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. + + + +[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 327b6caa..c0204d7e 100644 --- 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! -- 2.25.1