How to report issues in Maxima

We should probably put together a guide to reporting issues in Maxima that
we can point users to.

Many other projects have guides like that, and ours will probably be 90%
the same as them, with a few twists specific to Maxima.

Some examples roughly in my order of preference:

   - Stackoverflow --
   https://stackoverflow.com/help/minimal-reproducible-example
   - Mozilla/Bugzilla --
   https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html
   - Gnu Emacs --
   https://www.gnu.org/software/emacs/manual/html_node/emacs/Understanding-Bug-Reporting.html
   - Latex -- https://minimalbeispiel.de/mini-en.html
   - generic -- https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
   - R -- https://www.r-project.org/bugs.html

I had NotebookLM summarize these concisely and then edited it a log to
improve it and make it more applicable to Maxima. Here is what I came up
with.

*THIS IS A DRAFT! Please improve!*


   - *Before You Report:*
      - *Restart Maxima. *Problems often come from something you did
      earlier in the session.
      - *Disable any initialization files. *On the command line, you can
      run *maxima --no-init *to turn off initialization files.
      - *Read the manual for the command you're using. *Even if the
      behavior is surprising to you, it may be intentional. Of course, you
      can still suggest that the command be changed.
      - *Update Maxima, and re-check in the updated version.*
      - *Don't panic. *Write down exactly what you see before trying to
      find a workaround.
   - *What to Include in Your Report:*
      - *A clear title:* Write a brief title (10 words or less) that
      describes the specific problem. This can be as simple as *trigtools:
      trigfactor(1+x) gives error*.
      - *Step-by-step instructions (reproducibility):* Provide precise
      instructions detailing exactly what you entered so the developer can
      recreate the problem on their own computer. If you loaded your own files,
      include the *relevant part *of their content. Do not expect
      developers to download your packages from the internet.
      - *Expected vs. Actual results:* Clearly state what the software *did*
      and what you *expected *it to do. It may be obvious to you that for
      your matrix *M*, *eigenvalues(M) *should yield *[[-1,1],[1,1]]*, but
      it may not be to the developer. Although it can be useful to
motivate your
      example, do not assume that the developer understands your application
      field (optics, differential geometry, ...), and do not describe
the problem
      in terms of your field (not "the result violates conservation of energy",
      but "*a-b* must be identically zero").
      - *Exact error messages:* Provide the full text of any error messages.
      - *System details:* Report the information from *bug_report()*. A
      concise version is Maxima 5.49.0, SBCL 2.5.1, WSL on Windows 11, x86. If
      you are using a front end like wxMaxima, XMaxima, Imaxima, Maxima on
      Android, SageMath, etc., cite its version number and make sure
to report on
      the *Maxima* commands that failed. Most of us aren't familiar with
      SageMath, for example.
      - *Just the facts:* Focus strictly on what happened. Avoid guessing
      *why* the bug occurred or telling the developer how to fix it. If you
      have a workaround or a patch, supply it.
   - *Keep It Simple (Provide a "Minimal Example"):*
      - *Only include relevant material:* If you have a 30-line batch file,
      most of it is probably not needed; strip out everything (images,
      formatting, or text) that isn't absolutely necessary to trigger
the problem.
      - *Divide and conquer*: If you don't know what is causing the error,
      slowly remove pieces of your file or steps from your process one
at a time.
      When the problem stops happening, you've found the exact cause.
      - *Test your simplified version:* Before submitting your report,
      double-check that your shortened steps or simplified file still actually
      cause the problem to happen.

_______________________________________________
Maxima-discuss mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/maxima-discuss