How to properly report a bug

We definitely appreciate all of the feedback we have received over months of testing.  Thank you to all the beta testers!!

But, truth be told, some feedback is more actionable than others.  "It doesn't work" is not particularly useful -- clearly it works for us, or we would not have unleashed nvUltra onto the world.

So there are a few possibilities:

1. Some particular thing was never tested by us, and never worked.  For example, Brett and I both speak English as our native languages.  It's exceedingly rare that I write anything in German or French anymore (sadly my daily life is English-centric and I am not in school anymore, so I don't have the same opportunities as college to write in other languages.  Hopefully that will change someday.) So if there is something specific to a different language or typing input (e.g. 2-Set Korean), there is a good chance that we are not able to test it in the same way that a native or near-native speaker would.  To help us with these issues, we need specific instructions to help us replicate the problem and track it down.

2. Some things worked previously, and were tested, but then a regression error occurred when adding a new feature or fixing another bug.  I have pretty extensive test suites in place for the core text engine, but the higher level functionalities (e.g. the GUI) are more difficult to properly test in the same way that a user uses them.  For these problems, we also need specific instructions to recreate the problem, but sometimes the answer might be more immediately obvious if it is identified immediately after making the offending change.

Another way of breaking things down:

1. There is a problem with nvUltra itself.  Please do make sure that the problem has not already been fixed by using the latest version of nvUltra.  The "Check for Updates" menu will take care of that for you.

2. There is a problem with the way nvUltra interacts with other software (sometimes macOS, more often some other application that is running in the background.) . Creating a new macOS user (or quitting all running applications and menu bar programs) can often help distinguish between these.

3. There is a problem on your computer unrelated to nvUltra, but happens to show up when using nvUltra. (In the years I have been supporting other macOS users, I have come to realize that sometimes you actually do still have to reboot a Mac...)

4. And sometimes it is good old fashioned user error.  Obviously we like to consider this as an option only after other causes have been excluded.

Helpful information:

* The most helpful information is a crash report if nvUltra actually crashed, and one was generated.  Please send this to us as an attached file rather than pasting the text in the forums.  The formatting of these files matters when trying to symbolicate them.

* Information about your setup -- version of macOS, version of nvUltra, the actual file if there is a particular problematic file, or a sample file if it happens "all the time".

* Description of steps to reproduce -- if you can reproduce the bug at will on your machine, and can describe that for us so we can reproduce it, then we can identify and fix the problem almost all of the time.  Obviously we can't fix problems with macOS (over the years I have only identified a handful of issues that were almost certainly macOS problems.  In all but one or two, I could work around the problem.)

* Information about the results you *did* get vs the results you *expected* to get.  Sometimes a bug only seems like a bug, and was in fact the proper behavior.

# Non-crashing bugs

Sometimes bugs don't generate a crash.  We might sometimes need some additional debugging information from you.  To enable this, in the Terminal type:

`defaults write com.multimarkdown.nvultra STDebugLevel 10`

Now debug messages will be written to Console, which can be launched from /Applications/Utilities/Console.app. In Big Sur you have to start "streaming" at the top before the messages are displayed.

This will generate a *lot* of information, so you only need to test for a little bit.  Use a file without any confidential information, because some of the file contents are included in the debugging information.  Filter the display for `nvultra` in the searchbar in the upper right and send the contents to me via email and I'll dig through them.

Make sure to set the debug level back to 0 when you're done: `defaults write com.multimarkdown.nvultra STDebugLevel 0`

# "nvUltra runs too slowly"

One type of bug report deserves special mention.  I have been using the core of nvUltra for over a year now.  Brett has been using it for almost a year.  And very shortly after starting to use it, it has become the primary writing tool for both of us.  In that time, performance for both of us has generally been fantastic.  Sometimes a new feature causes a slow down that has to be tracked down and fixed.  But that has been relatively rare.  So if it is running slowly on your machine, we'll need specifics to help track it down.

* Again, the basics are helpful -- a sample file that is slow.  Or a sample folder that is slow.

* Use Activity Monitor to get an idea of CPU and memory usage of nvUltra and other applications.  Is nvUltra slow, or are there other processes that are competing for CPU time?

If things are *truly* slow without an explanation, the most helpful way to identify the problem is with time profiling.  This tracks which sections of code require the most CPU time, and is how developers speed up performance (identify slow steps and speed them up when possible.) . Steps to do this on your machine (if you have Xcode installed) are here:

https://gist.github.com/loderunner/36724cc9ee8db66db305#profiling-with-instruments

Basically:

1. identify the process id (pid) of nvUltra -- `ps aux | grep nvUltra` . For example, pretend the pid you find is `1234`

2. Run `instruments` with nvUltra as the target.  This command runs for 30 seconds, and you really want that 30 seconds to be spent on whatever is running slowly for you.  So if you're having trouble typing, spend the entire 30 seconds typing.  You can shorten (or lengthen) the time by changing the 30000 to something else. (Remember that 1234 is the sample pid from step 1)

`instruments -l 30000 -t Time\ Profiler -p 1234`

This will generate a profile on the Desktop.  Send this file to me and I will use it on my machine to try to figure out what is taking so much time.  I might still need the problematic file in order to really see what is triggering the issue.

It is also possible to sample without installing Xcode, but I have yet to be able to get the resulting profile into something useful.  So for now, that approach is not particularly helpful unless something obvious happens to jump out.

# Thanks!!

We truly appreciate all of the bug reports and feature suggestions that we have received since starting this process.  nvUltra would not be the app it is now without your help.  And we are excited about additional ideas for the future that we hope to be able to implement!!   Thank you!!