How to file a bug

There are a few simple rules to follow when filing a bug.

Bug reports that don't follow this can be annoying and hard to handle.

So below a list of tips. Also you could read Simon Tatham's (funny) HowTo:

1. Check the bugtracker and F.A.Q if there is already a report.Edit

This is important. It can cost a lot of time and energy of the developer to answer the same question over and over again.

The bug tracker is here:

2. Stay current

If you run a version older then the latest stable release, the bug might already be fixed. Install a newer version and check if it is fixed.

There are few things more painful than spending a lot of time working to communicate and understand a problem only to discover later that you're on an older version. This is a waste of your time and ours.

2. Provide basic information

This step is often forgotten.

  • The version of the software (gmpc in this case).
  • The version of mpd.
  • If you know, since what version/revision that bug first appeared.
  • The version of important libraries it uses. If you don't know, include atleast version of distribution. f.e. on ubuntu 8.10 i386.
  • The installed plugins.

In gmpc, paste the output of gmpc --version in the additional information box. (In gmpc 0.18.1 and above you can get this information by doing gmpc --bug-information. this will show a popup with the information. gmpc --version will not show all the info.)

Example output:

Gnome Music Player Client
Copyright 2003-2009 Qball Cow

Tagline                  : ♯♪ + ♭♪ = ☺
Version                  : 0.17.96
Revision                 : e9cc0ef
Libmpd version           : 0.17.97-git
GTK+ version             : 2.14.4
Libcurl version          : 7.18.2
Platform                 : *nix

Website                  :
Getting help             :

Options enabled:
X session management     : Enabled
NLS Support              : Enabled
Multimedia Keys          : Enabled
Libegg's trayicon        : Disabled
System libsexy           : Enabled
Mac integration library  : Disabled
Use ~/.config/ dir       : Disabled
Debug timing             : Disabled
Maintainer mode          : Disabled

As you can see, it is detailed and provides me with a lot of information.

3. Provide a detailed bug report

  • Clearly describe, step by step, the problem. A small step by step guide telling us how to reproduce the bug can save a lot of confusion.
  • The actual result you get and what you expected.
  • Don't think we can guess what you are looking at, or understand what you mean. We might not call it that way, or it might apply to different parts.
    Use screenshots if you are not clear how to call something.
    e.g. "The search bar" is not clear. Is this the search bar in the play queue? in the search browser? in the file browser? etc.

This is not a good bug report:

the search bar does not save whare it was last time gmpc quit . It always starts again showing the default options ie search for artist in database .
  • Don't turn it in a fairy tale. It DOES NOT MAKE THINGS CLEAR. An example:
JOHN: holy cow I want to listen to my Mozart pieces.... but they're scattered all across some 20 folders, I can filter them out, but It won't do me any good... I could properly sort my folders... which would take forever, since my server is on the other side of the planet, or I can make a new playlist which will take me half an hour or so...
JANE: or you could install the new gmpc version which renders a temporary discontinuous playlist once a filter is applied so that YOU HEAR WHAT YOU SEE, also, it has a new feature that highlights the now playing file in filtered mode too, so that you SEE WHAT YOU HEAR
JOHN: yaya dont gimme that shirt I can do well without downloading the newest version [...] there, I made myself a new Mozart playlist, why would I need bloaty features?
JANE: (runs off crying)
[1 hour later]
JOHN: I feel like ditching Mozart.... time for some Images in an Exhibition... also scattered among many folders.... uhm, Jane, what was that about a new version? Jane? Jane?! Jane?!?! :((
  • Only one bug per report.
  • Don't demand changes. You are not the only user.
  • Don't be rude.
  • Don't be afraid to include a patch fixing the bug.

4. Additional information.

  • If gmpc crashes, try to get a backtrace, include this.
  • Run gmpc with --debug-level=3 and see if it outputs interesting information at the time of the crash/bug.
  • If the mpd log file contains information about the bug, include this.

5. Where to report the bug

The bug belongs in the bug tracker. IRC, IM, e-mail or the Forum is not the place to file bugs.

If I have time I check the bugtracker to see if there are bugs that should be fixed.

6. Once you get a comment on the bug

  • Try to answer quickly.
  • Accept an answer you might not wanted to hear. Don't get stuck in a loop repeating the same thing.
    If you don't agree, try to explain your point of view.
  • Test possible fix as soon as possible. This helps improving the software.

How to file a feature request

Feature requests belong on the bug tracker. I know you might not consider it a bug, but the bugtracker is a nice centralized placed to store it.

Before you file a feature request please take the following in account: Edit

  • Is it already available in a newer version.
  • Is it useful for other people. 1001 options to tweak little things are not welcome.
    An example is a request for adding an option to change double click behaviour.
  • Is it realistic.
  • Is it possible to implement, or does it require functionality in mpd that it does not have.
  • Does it fit into gmpc?
    F.e. requesting ipod support in GMPC is pointless. It is mpd that has access to the music and maintains the database, GMPC is just the frontend.
  • etc.

When filing a feature request Edit

  • Include one or more use-cases.
  • Be clear and detailed when describing what you want.
    • Include a mockup
    • Describe step by step how you would use it and what the response from the program is.
    • Indicate what the expected behaviour should be (with the feature request).
  • Don't demand anything.
  • Try to think of the impact of the feature request. if possible include that.
  • Include the version of gmpc you are using.
  • Before writing patches first check if the feature would be accepted.
  • Remember that patches are welcome.
  • No fairy tales!