GNOME.org
 

[gimp-web] content: improve the bugs/ section.

commit d6bbdc1face936f4d154031f5a9b66def22aef37
Author: Jehan <jehan girinstud io>
Date:   Wed Sep 21 20:19:29 2022 +0200

    content: improve the bugs/ section.
    
    Move around text between the "index" and "report" pages in the bug section. The
    index contain the generic info on what to do when you find a bug, the fact you
    need to search for duplicates, and the "Enhancing Bug Reports" section.
    
    The "Reports" page on the other hand now focuses on how to report a bug. The
    fact you searched for duplicate in particular is assumed as already done. The
    Security Bugs section is also moved there, in the end. After all, it's just a
    special case of the normal procedure.

 content/bugs/index.md  | 102 ++++++++++++++++++++++++++++---------------
 content/bugs/report.md | 114 ++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 161 insertions(+), 55 deletions(-)
---
diff --git a/content/bugs/index.md b/content/bugs/index.md
index fccb5e26..8d1a37d2 100644
--- a/content/bugs/index.md
+++ b/content/bugs/index.md
@@ -1,35 +1,45 @@
-Title: Bugs 
+Title: Bugs
 Date: 2015-08-17T11:09:31-05:00
 Modified: 2019-03-14T11:06:49-06:00
 Authors: Pat David
 Status: hidden
 
-<a href="https://gitlab.gnome.org/GNOME/gimp/issues/new"; title="Report a bug for GIMP!" class='reportBug'>
-Report an issue here!
-</a>
-
-<form action="https://gitlab.gnome.org/GNOME/gimp/issues?scope=all&utf8=%E2%9C%93";>
-<label>Search for an existing bug:<br/>
-<input type="text" name="search" placeholder="e.g.: 'font loading'" id='bugInput' /></label>
-<input type="hidden" name="state" value="all">
-<input type="submit" value="Submit"/>
-</form>
+If you think you found a bug, it is very important to report it. If the
+developers don't know about what might be broken, they can't fix
+it. So there you are at your computer trying to do something with GIMP
+and it freaks out at you. It can be a frightening experience at times.
 
-Making good bug reports is a great way to help increase the software quality of GIMP. A good bug report 
provides unambiguous step-by-step instructions on how to reproduce the bug, what result is expected, and what 
the actual result is. Good bug reports make it easy for the developers to reproduce and fix the bug.
+## First, Next, Third
 
-Related to bug reports are enhancement requests. An enhancement request should never be filed without prior 
discussion on the gimp-developer [mailing list](/discuss.html). This is to make sure that the enhancement 
requests that are filed are well-specified and aligned with the overall goals the developers have for GIMP.
+First
+: Get out a piece of paper or open a text file and scribble down everything you can remember about what you 
were doing when it happened. Also write down the exact wording of any error messages you received. If 
relevant, take a screenshot.
 
+Next
+: Go away and yell and scream and do whatever you need to do to relax again.
 
-## Bug How Tos
+Third
+: Check if your bug has been reported already by searching if any report in the
+[Current Issue Lists](#checking-existing-reports) looks like it.
+If it has, you can still help. See the section: [Enhancing Bug
+Reports](#enhancing-bug-reports). Otherwise you will need to [report
+it](#reporting-a-bug).
 
-Since correctly submitting a bug report requires you to use tools you may have not used previously, we have 
created two documents. The first helps you to learn GitLab issues, which is the bug system used by GIMP 
developers to track bug reports. If you are fixing a problem yourself, the second document shows you how to 
properly create and submit a patch.
+## Checking Existing Reports
 
-*   [How To Report an Issue]({filename}report.md)
-*   [How To Create and Submit a Patch](/bugs/howtos/submit-patch.html)
+<form action="https://gitlab.gnome.org/GNOME/gimp/issues?scope=all&utf8=%E2%9C%93";>
+<label>Search for an existing bug in GIMP:<br/>
+<input type="text" name="search" placeholder="e.g.: 'font loading'" id='bugInput' /></label>
+<input type="hidden" name="state" value="all">
+<input type="submit" value="Submit"/>
+</form>
 
-## Bug Lists
+Below are different links into GitLab which show you lists of open and closed
+bugs for GIMP itself, its user manual or its website. You can search manually,
+but these links are often a convenient start. With the help of the lists below
+you should be able to see if the bug you have found has already been reported.
 
-Below are different links into GitLab which show you lists of open and closed bugs. You can also search 
manually, but these links are often more convienient. With the help of the lists below you should be able to 
see if the bug you have found has already been reported. If it has been reported, and you have additional 
information, please add a comment with the additional information!
+If it has been reported, and you can give more information, please [add a
+comment with the additional information](#enhancing-bug-reports)!
 
 ### GIMP bugs
 
@@ -46,29 +56,53 @@ Below are different links into GitLab which show you lists of open and closed bu
 
 *   [Feature proposals](https://gitlab.gnome.org/GNOME/gimp/issues?label_name%5B%5D=1.+Feature)
 
-* [Submit a new GIMP issue](https://gitlab.gnome.org/GNOME/gimp/issues/new)
+### GIMP Manual bugs
 
+*   [Open issues](https://gitlab.gnome.org/GNOME/gimp-help/issues)
 
+### GIMP Website bugs
 
-### GIMP Help bugs
+*   [Open issues](https://gitlab.gnome.org/Infrastructure/gimp-web/issues)
 
-*   [Open issues](https://gitlab.gnome.org/GNOME/gimp-help/issues)
+## Reporting a Bug
 
-*   [Submit a new GIMP Help 
issue](https://gitlab.gnome.org/GNOME/gimp-help/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=)
+If you already know GIMP's bug reporting procedure, just:
 
-### GIMP Website bugs
+* <a href="https://gitlab.gnome.org/GNOME/gimp/issues/new"; title="Report a bug for GIMP!" class='reportBug'>
+report an issue in GIMP
+</a>
+* <a href="https://gitlab.gnome.org/GNOME/gimp-help/issues/new"; title="Report a bug for GIMP Manual!" 
class='reportBug'>
+report an issue in GIMP Manual
+</a>
+* <a href="https://gitlab.gnome.org/Infrastructure/gimp-web/issues/new"; title="Report a bug for GIMP 
Website!" class='reportBug'>
+report an issue in GIMP Website
+</a>
 
-*   [Open issues](https://gitlab.gnome.org/Infrastructure/gimp-web/issues)
+Otherwise please read our tutorial: [How To Report an Issue]({filename}report.md)
+
+ℹī¸  Note that if you are looking for fixing the problem yourself, you might
+rather be interested by our [🧑‍đŸ’ģ developer
+website](https://testing.developer.gimp.org/core/), which contains tutorials on
+how to build GIMP and submit your first patch.
+
+## Enhancing Bug Reports
+
+If someone has already reported the bug you encounter:
 
+* Read the bug report and the comments carefully. Make sure every bit of
+  information you know about the bug is in there. If your version is
+  different or you had a slightly different experience with the bug, add
+  a comment providing your information.
 
-*   [Submit a new GIMP website 
issue](https://gitlab.gnome.org/Infrastructure/gimp-web/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=)
+* Check the status of the bug carefully. If developers are requesting
+  some information and the original reporter doesn't answer, see if you
+  can provide the needed information.
 
-## Security bugs
+* Do not add a "*me too*" comment unless your comment provides additional
+  information that might be helpful for debugging.
 
-Some bug reports may be related to security issues. 
-For example, a file plug-in may be vulnerable to a buffer overflow allowing arbitrary code execution when 
loading an image. 
-We believe that the best way to report these vulnerabilities is through our GitLab issues, as described 
above. 
-This will ensure that the bug is reviewed and handled quickly (if necessary, a developer may decide to hide 
a sensitive bug report from other users until it is fixed). 
-But if you really do not want to use GitLab for security reports and you do not mind some extra delay, you 
can also contact a limited set of GIMP developers by mail @gimp.org, using the special alias "security". 
-What will happen next is that a developer will review the issue and submit it in GitLab, usually as a hidden 
bug report only visible to developers. 
-This will take a bit longer than if you directly submit the bug yourself, but we know that some people have 
a policy of not disclosing security vulnerabilities publicly, so we provide that address for their 
convenience.
+**Note**: if you are unsure the existing report really describes the
+same bug, it is better to create a new report, though it is a good idea
+to mention the report ID of this other bug which looks alike. Other
+contributors may be able to make sense of whether it is a duplicate or
+not. If so, they will simply close as duplicate.
diff --git a/content/bugs/report.md b/content/bugs/report.md
index a45c1cf9..ca89061a 100644
--- a/content/bugs/report.md
+++ b/content/bugs/report.md
@@ -4,34 +4,52 @@ Modified: 2018-06-08T11:46:47-06:00
 Authors: Pat David
 Status: hidden
 
+Making good bug reports is a great way to help increase the software quality of GIMP. A good bug report 
provides:
 
-If you find a bug or think you find a bug, it is very important to report it. If the developers don't know 
it is broken (or might be broken), they can't fix it. So there you are at your computer trying to do 
something with GIMP and it freaks out at you. It can be a frightening experience at times.
+* unambiguous step-by-step instructions on how to reproduce the bug;
+* what result is expected;
+* and what the actual result is.
 
+This makes it easy for the developers to reproduce and fix the bug.
 
-## First, Next, Third
+Related to bug reports are enhancement requests. It is recommended to discuss
+enhancements with developers first, for instance on
+[IRC](/discuss.html#irc-matrix) or in the `gimp-developer` or `gimp-gui`
+[mailing list](/discuss.html#mailing-lists). This is to make sure that the
+enhancement requests that are filed are well-specified and aligned with the
+overall goals the developers have for GIMP.
 
-First: Get out a piece of paper or open a text file and scribble down everything you can remember about what 
you were doing when it happened. Also write down the exact wording of any error messages you received.
+[TOC]
 
-Next: Go away and yell and scream and do whatever you need to do to relax again.
+## Reporting a Bug
 
-Third: Check to see if your bug has been reported yet. Go to the [Current Issue 
List](https://gitlab.gnome.org/GNOME/gimp/issues) to see if something that looks like your bug has been 
reported yet. Don't worry if it has, you can still help. See the section: [Enhancing Bug 
Reports](#enhancing-bug-reports). If you can't find something that sounds like your bug there, you will need 
to report it.
+The goal is to give the developers as much information as possible to help them understand what needs to be 
fixed:
 
+1.  Use `gimp --version` or the about dialog (`Help → About GIMP`) to check your
+    GIMP version. Next compare to the most recent GIMP release on
+    [www.gimp.org](https://www.gimp.org/). If your GIMP is old, update and try
+    to reproduce the bug. Your bug may have been fixed in a recent release.
 
-## Getting Ready to Report and Reporting a Bug
+2.  Attempt to reproduce the problem. Go do what you were doing when it happened and see if you can trigger 
the bug again.
 
-The goal of the following is to give the developers as much information about what goes wrong as possible. 
This helps them find out what needs to be fixed.
+    If you know how to do so, start the program from a terminal.
+    Sometimes it will output helpful error messages. After reproducing
+    the bug, copy the error messages from your terminal so you can paste
+    them in the bug report. It is better to give too much information
+    than not enough.
 
-### The Steps
+    To narrow down the exact cause of the problem, attempt to reproduce
+    it in other ways. Prepare yourself to explain how to reproduce it in
+    your bug report. If you are running GIMP in another language, try
+    [switching GIMP to
+    English](https://docs.gimp.org/en/gimp-fire-up.html#gimp-concepts-running-language)
+    so you can report menu items exactly with the English menu item
+    name. It simplifies developers' task.
 
-1.  Use `gimp --version` or the about dialog (`Help → About GIMP`) to check your GIMP version. Next check 
with [www.gimp.org](https://www.gimp.org/) to see what the most recent GIMP release is. If your GIMP is old, 
update then try to to reproduce the bug. Your bug may have been fixed in the most recent release. If you are 
running GIMP from Git, update and and recompile.
+    If you cannot reproduce the bug and don't have any reliable information, reporting might be fruitless 
and only waste everyone's time.
+    If it recurs, consult with appropriate [discussion channels](/discuss.html). Perhaps someone else can 
find the key to reproducing it.
 
-2.  Attempt to reproduce the problem. Go do what you were doing when it happened and see if you can do it 
again.
-
-    If using GIMP for GNU/Linux, start the program from a terminal with the command `gimp`. Sometimes the 
program will output error messages that can help. This is especially important if GIMP crashes completely 
without warning. After reproducing the bug, copy the error messages from your terminal into somewhere where 
you can save them for the bug report. It is better to give too much information than not enough.
-
-    To narrow down the exact cause of the problem, attempt to reproduce it in other ways. Prepare yourself 
to explain how to reproduce it in your bug report. If you are running GIMP in another language, try 
[switching your GIMP to English](https://docs.gimp.org/en/gimp-fire-up.html#gimp-concepts-running-language) 
so you can report menu items exactly with the English menu item name. It helps - developers generally 
understand English). If you cannot reproduce the bug, assume it was some weird freak event and don't report 
it. If it recurs, consult with your appropriate [user mailing list](/discuss.html). Perhaps someone else can 
find the key to reproducing it.
-
-3.  Go to [GIMP issues](https://gitlab.gnome.org/GNOME/gimp/issues/). If you don't have a login yet, follow 
the directions to create one. The reason to do this and report a bug with your e-mail address is so the 
developers can contact you if they have any questions. That way if we miss some useful tidbit of debugging 
information, they can tell you what to do to get it. Log in.
+3.  Go to [GIMP issues](https://gitlab.gnome.org/GNOME/gimp/issues/). If you don't have a login yet, follow 
the directions to create one.
 
 4.  Select "New issue".
     <figure>
@@ -54,14 +72,68 @@ The goal of the following is to give the developers as much information about wh
 
     Remember, try to be as clear and concise as possible!  This is immensely helpful in tracking down what 
the problem is and how to possibly fix it.
 
-    Finally, please add the output you get from running `gimp --version --verbose` to your bug report.
+    Finally, please add the output you get from running `gimp --version
+    --verbose` to your bug report, and publish the report by clicking the blue
+    "*Create issue*" button.
 
-## Enhancing Bug Reports
+6.  You should not expect immediate responses as contributors have a lot
+    of tasks, though they try to be reactive when possible. They may ask you for
+    more information and will tell you what to do to get it (you should get
+    email notifications). We don't expect you to do answer immediately as well,
+    though we expect you to follow up eventually.
 
-If someone has already reported a bug like yours, read the bug report carefully. Read through all the 
additional comments. Make sure every bit of information you know about the bug is in there. If your version 
is different or you had a slightly different experience with the bug, add a comment providing your 
information. Check the status of the bug carefully. If it is marked "NEEDINFO", see if you can provide the 
information needed. Do not add a "me too" comment unless your comment provides additional information that 
might be helpful for the developer.
+7.  If you later get more information (like a more specific error message or
+    fancy stuff like a trace), add a comment to your original bug with that
+    information.
 
-If you have provided a bug report and later get more information (like a more specific error message or 
fancy stuff like a trace), add a comment to your original bug with that information. It is especially 
important to add a comment if you somehow resolve your bug. For example, you update something else on your 
system and the bug no longer appears. In that case, add a comment describing what you updated from what 
version to what version that resolved the bug.
+8.  It is especially important to add a comment if you somehow resolve
+    your bug. For example, you update something else on your system and
+    the bug no longer appears. In that case, add a comment describing
+    what you updated from what version to what version. This helps everyone and
+    saves a lot of time which can be used to fix other bugs or implement nice
+    features.
 
 ## The Wait Patiently Part
 
-*Whee!!* You survived! If you managed to get through all this and submit your bug report, be happy. Be 
proud. You will later get e-mails about your bug. It might include a request for more information. If you get 
something that says your bug is not a bug, do not be discouraged from reporting in the future. Next time it 
might be. Submitting careful bug reports and providing additional information where possible helps make GIMP 
better. The day will come where you submit a bug and later get an e-mail that says your bug is "FIXED" or 
"RESOLVED". Then you will know that some developer out there found your bug, reproduced it, and fixed it.
+*Whee!!* You survived! If you managed to get through all this and submit your
+bug report, be happy. Be proud as a contributor to the community!
+
+You will later get e-mails about your bug. It may not be immediate. Since GIMP
+is developed by a community, by volunteers, sometimes it may take some time.
+Though we try to always answer.
+Similarly when we ask you questions, we don't expect you to answer immediately,
+though we expect you to answer eventually. Otherwise it makes no sense. The
+basis is that we acknowledge that everyone has a life outside of GIMP, you as
+much as the developers.
+
+Answers might include a request for more information. If you get something that
+says your bug is not a bug, was already fixed or is a duplicate to another
+report, do not be discouraged from reporting in the future. Next time it might
+be. Submitting careful bug reports and providing additional information where
+possible helps make GIMP better. The day will come where you submit a bug and
+later get an e-mail that says your bug is "FIXED" or "RESOLVED". Then you will
+know that some developer out there found your bug, reproduced it, and fixed it.
+🎉
+
+## Security Bugs
+
+Some bug reports may be related to security issues.
+For example, a file plug-in may be vulnerable to a buffer overflow allowing arbitrary code execution when 
loading an image.
+
+We believe that the best way to report these vulnerabilities is still through
+our [GitLab issues](https://gitlab.gnome.org/GNOME/gimp/-/issues), as described
+above. This will ensure that the bug is reviewed and handled quickly.  The only
+difference is that you will want to check the box "*This issue is confidential
+and should only be visible to team members with at least Reporter access.*" in
+the bug report creation form. This will hide the bug report from anyone else but
+core members.
+
+But if you really do not want to use GitLab for security reports and you do not
+mind some extra delay, you can also contact a limited set of GIMP developers by
+mail `@gimp.org`, using the special alias `security`.  What will happen next is
+that a developer will review the issue and submit it in GitLab, usually as a
+hidden bug report only visible to developers.
+
+This will take a bit longer than if you directly submit the bug yourself, but we
+know that some people have a policy of not disclosing security vulnerabilities
+publicly, so we provide that address for their convenience.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]