How to file a bug properly

GPAC is becoming quite a large piece of software and, unfortunately despite our care, is not bug-free… This is where you, as GPAC users, can help. If you discover a problem, you can report it using our GitHub bug tracker (old bugs were in our Sourceforge bug tracker ) .

Filing a bug, if this is done well, is the best way to ensure that the problem will be fixed. However, if the bug is not filed correctly, it is the best way to ensure that it won’t get fixed. This post gives guidelines on how to file a bug, properly.

  1. Before filing, the first thing to do is to make sure the bug, or a similar one, has not been reported by someone else. You can search on GitHub. If you find a similar bug, you may complement that bug by adding the information indicated below.
  2. If you did not find an existing relevant bug, the second thing to do is to make sure your problem has not been fixed already. For that, check the latest version of the code: either getting the source from on GitHub and recompiling it; or downloading the latest nightly build.
  3. If the above steps did not give you the answer to your problem, you can now file a new bug.
    In the bug, you must provide the following information:
  • A meaningful title. It will then be easier to sort the bugs, search through them …
  • Some relevant tags to help searching the bug: e.g. MP4Box, MP4Client, DASH, MP4, Subtitles, Synchronization, Streaming, Rendering, …
  • Details about the GPAC tools you are using:
    • how you obtained GPAC:
      • if you compiled it yourself,
      • or if you’ve downloaded from our download page.
        NOTE: if you’ve downloaded GPAC built by someone else, make sure the problem exists with an official build and report only that.
    • which Operating System you are running on: Windows, Mac, Linux, iOS, Android…
    • which version of the Operating System (Win7, Ubuntu 12.04, Mac OS X 10.7, …)
    • which architecture (32 bits, 64 bits)
    • which application you are using: MP4Box, MP4Client, MP42TS, DashCast, …
    • which version of GPAC you are using.
      Versions look like: “GPAC version 0.5.1-DEV-rev4663”.
      The last part is the version number from our code repository. This is the most important part. The version can be obtained running the following command line:

  • A clear description of how to reproduce the bug, step by step
    • including which tools were used (from other projects: x264, ffmpeg, vlc …)
    • the exact command lines you used, if any
  • A clear description of the problem
    • why you think it is a bug:
      • what was expected
      • what was the result you obtained
    • if the problem is: a regression (was working before, in which case indicate which version was working), a new problem (has never worked), or if you don’t know
    • if the problem happens: all the time, sometimes, or randomly
    • the entire output of the tools that creates the problem, i.e. you can copy/paste the output of MP4Box or MP4Client or generate log files.You should also provide the configurations files that tools used: e.g. “.gpacrc” or GPAC.cfg, or dashcast.cfg, or dashctx.cfg …NOTE: You may use the GPAC log tools to provide us with more info for instance using the following command line:

  • A link to the content that creates the problem:
    • It is easier for us to debug if we have the content to reproduce the bug. You should provide a URL to the content to be used to reproduce the problem (e.g. MP4 files, …)
    • You may place large files (logs, MP4, or others) on some download site of your choice (such as WeTransfer or this French site for files up to 10GB with FTP resumable transfers).
  • If this is a compilation problem, you must report:
    • the environment you use: Linux distro, Windows, Mac …
    • which compiler you use (gcc, …) and which version
    • if applicable, the result of the configure command, the content of the config.mak
    • the complete output of the compilation include all warnings, errors, …



One thought on “How to file a bug properly

Comments are closed.