Re: How to report issues in Maxima

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]> 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
>    - 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
>

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