Re: How to report issues in Maxima

Provided we can keep this guide short, maybe it can be included in the output of `bug_report'.

This could also be the right time to finally define the meaning of `Priority` and include it as a suggestion.
Here are a few additional points we could add:

  *
Performance Issues: If you are reporting a calculation that hangs or runs out of memory, please make sure the code works correctly for simpler cases.
  *
Usage Support: Please direct questions regarding Maxima's usage and installation to the Maxima mailing list, reserving the bug tracker for bugs.
  *
Test Cases: If you can suggest test cases, please include them in your report. A test should use the following format:
Input;
Expected output$








________________________________
From: Richard Fateman <[email protected]>
Sent: Sunday, June 14, 2026 5:37 PM
To: Stavros Macrakis <[email protected]>
Cc: <[email protected]> <[email protected]>
Subject: Re: [Maxima-discuss] How to report issues in Maxima

Caution: Non-NU Email

A good start.

Maybe worth adding some things more specific to Maxima,  like this:

 Rather than pasting 2-d math displays into an email report you can run the command
display2d:false;
which will cause Maxima to print using a more linear style,  usually better for cut and paste.

It is possible to trace functions or commands in Maxima including ones you
define yourself. If you think that the problem is in some command, say f, you may
be able to narrow the scope of the error by first saying trace(f).

While it is possible to examine Maxima's computations at a more granular level by
looking at its source code in its implementation language (Common Lisp), it is
generally easier to isolate and report the issue at the "Maxima language" level.

.....
Also, how to make the user aware of the guidelines?  When an error message is printed?
........



On Sun, Jun 14, 2026 at 2:58 PM Stavros Macrakis <[email protected]<mailto:[email protected]>> wrote:
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<https://urldefense.com/v3/__https://stackoverflow.com/help/minimal-reproducible-example__;!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87NIyNJQfQ$>
  *   Mozilla/Bugzilla -- https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html<https://urldefense.com/v3/__https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html__;!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87Ny7gd6Yg$>
  *   Gnu Emacs -- https://www.gnu.org/software/emacs/manual/html_node/emacs/Understanding-Bug-Reporting.html<https://urldefense.com/v3/__https://www.gnu.org/software/emacs/manual/html_node/emacs/Understanding-Bug-Reporting.html__;!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87NXAtgcLg$>
  *   Latex -- https://minimalbeispiel.de/mini-en.html<https://urldefense.com/v3/__https://minimalbeispiel.de/mini-en.html__;!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87PBDZcJAg$>
  *   generic -- https://www.chiark.greenend.org.uk/~sgtatham/bugs.html<https://urldefense.com/v3/__https://www.chiark.greenend.org.uk/*sgtatham/bugs.html__;fg!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87OhZyOYwQ$>
  *   R -- https://www.r-project.org/bugs.html<https://urldefense.com/v3/__https://www.r-project.org/bugs.html__;!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87P4sV9weQ$>

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]<mailto:[email protected]>
https://lists.sourceforge.net/lists/listinfo/maxima-discuss<https://urldefense.com/v3/__https://lists.sourceforge.net/lists/listinfo/maxima-discuss__;!!PvXuogZ4sRB2p-tU!FgsPpRu2xsUiBUSG8j0u0ZK8HYBdHU-tbtegQyi4_BMqfdJR9jfIuUMwOE-V2dWtp95S87OkW4cvBg$>

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