[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] (no subject)
From: |
Mohammad Akhlaghi |
Subject: |
[gnuastro-commits] (no subject) |
Date: |
Fri, 27 May 2016 12:29:53 +0000 (UTC) |
branch: master
commit c011627efc46ee5d66d823a850c30d196e5a953d
Author: Mohammad Akhlaghi <address@hidden>
Date: Fri May 27 21:26:57 2016 +0900
Added links and explanation in "Report a bug"
Links to two nice essays on best ways to report a bug report were included
in the "Report a bug" section. I found these links in the Automake manual
and found them to be very useful. "Be descriptive" was also added as a
suggestion for a good bug report and some minor typos were corrected.
---
doc/gnuastro.texi | 33 ++++++++++++++++++++++++++++-----
1 file changed, 28 insertions(+), 5 deletions(-)
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 98ce3e8..7405e97 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -991,11 +991,11 @@ this environment, the transition is not necessarily easy.
To encourage you
in investing the patience and time to make this transition, we define the
GNU/Linux system and argue for the command-line interface of scientific
software and how it is worth the (apparently steep) learning curve.
address@hidden interface}, contains a short overview of the very
address@hidden interface} contains a short overview of the very
powerful command-line user interface. @ref{Tutorials} is a complete chapter
with some real world example applications of Gnuastro making good use of
GNU/Linux capabilities written for newcomers to this environment. It is
-fully explained, easy and entertaining.
+fully explained, easy and (hopefully) entertaining.
@cindex Linux
@cindex GNU/Linux
@@ -1193,11 +1193,33 @@ solved but not yet released and it is an urgent issue
for you, you can
get the version controlled source and compile that, see @ref{Version
controlled source}.
-To solve the issue as readily as possible, please follow these
-guidelines in your bug report:
+To solve the issue as readily as possible, please follow the following to
+guidelines in your bug report. The
address@hidden://www.chiark.greenend.org.uk/~sgtatham/bugs.html, How to Report
+Bugs Effectively} and @url{http://catb.org/~esr/faqs/smart-questions.html,
+How To Ask Questions The Smart Way} essays also provide some very good
+generic advice for all software (don't contact their authors for Gnuastro's
+problems). Mastering the art of giving good bug reports (like asking good
+questions) can greatly enhance your experience with any free and open
+source software. So investing the time to read through these essays will
+greatly reduce your frustration after you see something doesn't work the
+way you feel it is supposed to for a large range of software, not just
+Gnuastro.
@table @strong
address@hidden Be descriptive
+Please provide as many details as possible and be very descriptive. Explain
+what you expected and what the output was: it might be that your
+expectation was wrong. Also please clearly state which sections of the
+Gnuastro book (this book), or other references you have studied to
+understand the problem. This can be useful in correcting the book (adding
+links to likely places where users will check). But more importantly, it
+will be very encouraging for the developers, since you are showing how
+serious you are about the problem and that you have actually put some
+thought into it. ``To be able to ask a question clearly is two-thirds of
+the way to getting it answered.'' -- John Ruskin (1819-1900).
+
@item Individual and independent bug reports
If you have found multiple bugs, please send them as separate (and
independent) bugs (as much as possible). This will significantly help
@@ -1217,6 +1239,7 @@ make it as small as possible so it can easily be uploaded
and
downloaded and not waste the archive's storage, see @ref{ImageCrop}.
@end table
address@hidden
There are generally two ways to inform us of bugs:
@itemize
@@ -14765,7 +14788,7 @@ make your announcement, other people might contribute
to the branch before
merging it in to @file{master}, so this is very important. Also before
starting each issue branch from @file{master}, be sure to run @command{git
pull} in @file{master} as shown above, to start your branch (work) from the
-most recent history point and thus simply the final merging of your work.
+most recent history point and thus simplify the final merging of your work.