Reporting errors, bugs, issues - geoscience-community-codes/GISMO GitHub Wiki

Writing Support Requests

When submitting a support request, please help us provide a quick solution by providing detailed information. Ideally you should do enough work on your end to isolate the problem and create a "minimal working example" (abbreviated to "MWE" in software engineering circles). See MWE on Wikipedia.

While in principle we can sometimes puzzle through partial information to recognize what's going wrong for you, in practice this can take a lot of time that slows down our response, plus we may not be identifying the same things that you are seeing in context.

To help other GISMO users - including the developers - solve your GISMO problem, please attempt to make your problem as reproducible as possible. Include:

  • One or more complete sentences explaining what problem you see and why you consider it a problem, even if it may seem obvious to you.
  • Your m-file script or function that generated the error.
  • the line number that generated the problematic output (e.g. error message)
  • the output you received - e.g. error message(s)
  • what output were you expecting instead?
  • which difference between expected and observed is problematic
  • A short, reproducible test-case if appropriate
  • your operating system (MacOS, Linux, Windows) and version (e.g. macOS Mojave, Centos 7.5, Windows 10).
  • whether your version of GISMO is from a downloaded zip file, or from using git clone
  • for those using git, please open a terminal window and change to your GISMO directory, and then issue the command 'git status', and include the output in your report. See additional notes for git users at the bottom of this page.
  • your version of MATLAB (e.g. 2018a), you can find this with the 'ver' command. For example, I get this: >> ver ----------------------------------------------------------------------------------------------------- MATLAB Version: 9.4.0.813654 (R2018a) MATLAB License Number: 845111 Operating System: Mac OS X Version: 10.14.4 Build: 18E226 Java Version: Java 1.8.0_144-b01 with Oracle Corporation Java HotSpot(TM) 64-Bit Server VM mixed mode ----------------------------------------------------------------------------------------------------- MATLAB Version 9.4 (R2018a) Curve Fitting Toolbox Version 3.5.7 (R2018a) Image Processing Toolbox Version 10.2 (R2018a) Instrument Control Toolbox Version 3.13 (R2018a) Mapping Toolbox Version 4.6 (R2018a) Optimization Toolbox Version 8.1 (R2018a) Signal Processing Toolbox Version 8.0 (R2018a) Statistics and Machine Learning Toolbox Version 11.3 (R2018a)

In particular, it is not sufficient merely to cut-and-paste raw program output without any explanation of why you consider it problematic, then submit that snippet as the entirety of your support request.

Capturing your workspace variables

Note that MATLAB provides a couple of extra tools that can be really helpful. For example, if line 67 of your script (or function) generates an error, you can insert the following line between line 66 and 67 >> save myworkspace.mat This will capture all of the variables in your MATLAB workspace. If you send this, along with a copy of your script (or function), then it should help us reproduce the problem you are having.

Two ways of reporting problems

Bugs/errors/issues with GISMO should be reported via the GISMO Users Group.

Alternatively, issues can be posted directly on the GitHub Issue Tracker, but we do not recommend this as only the developers are likely to check this, and even then, very rarely. To learn how to make best use of the GitHub Issues tracker see this guide

Additional notes for git users

We highly recommend that GISMO users use git to clone and pull (update) their local GISMO repository, rather than download Zip files from Github or MathWorks file exchange. (See the Getting started page to git clone the repository).

If you open a terminal window (or command prompt on Windows) and cd (change directory) to the GISMO directory, you can then type:

git status

to see what branch you are on. For example, I see:

joule:GISMO glennthompson$ git status On branch develop Your branch is up to date with 'origin/develop'.

nothing to commit, working tree clean

The most important thing is the first 2 lines: On branch develop Your branch is up to date with 'origin/develop'.

This means I am on the "develop" branch, and that it is tracking the "develop" branch at the origin, which is the repository on GitHub. Most of you will be on the "master" branch instead.

However, if you are not up to date with the origin you will see a different message, prompting you to pull the changes. You do this with:

git pull

As I mentioned already, you are probably on the "master" branch. But this does not get updated often - only when there is an official release. So if you want to be more on the bleeding edge, and this is definitely helpful if we need to modify GISMO to fix an issue you are reporting, it is useful if you switch to the "develop" branch. All you need to do is:

git checkout develop

This will magically update all the files in your GISMO directly to match what the "develop" branch on GitHub. I can modify this branch on my computer, push the changes to github, and you can pull them down and test them on your computer.

To switch back to the master branch at anytime, just do:

git checkout master

This way of working makes it much easier to solve problems compared to downloading Zip files.