Reporting and Tracking an Issue

The main issue tracker for libzmq lives on GitHub.

Our process

We use the C4.1 process for working on ZeroMQ, which means that every change is tracked as an issue. You can either:

  • Define an issue for a problem and then propose your own patch, or wait for someone else to fix it, or
  • Come immediately with a patch, and submit that as a pull request, without a separate issue.

An ideal description for an issue goes:

Problem: (describe the problem here)
Solution: (describe your solution here)

Please do not create issues for ideas, suggestions, wishes, or feature requests. Come with clear problems and plausible solutions.

You can tag an issue as "Critical" if you wish. However there are only three ways to solve an issue in ZeroMQ:

  1. To work on it yourself and propose a patch;
  2. To pay someone else to work on it;
  3. To wait.

Also known as the "spend effort, money, or time" principle. What will not generally work, and is considered rude, is to ask others to spend effort, money, or time on your behalf.

The old Jira issue tracker

We used a Jira issue tracker for some years, which is now deprecated. People may still make issues there, though eventually we'll shutter it. If you have important issues in the Jira tracker, please take a moment to re-create them on the GitHub issue tracker. We will not be doing this automatically.

How to submit an issue

Before you submit an issue, test against the latest GitHub master. It's pointless to log an issue for a version of ZeroMQ we don't maintain. Secondly, check the existing open issues so you don't log an issue someone else already reported. You'd be surprised how often people do this.

If you're getting an assertion failure, put that in the title of the issue, "Assertion failure in somefile.cpp:1234". Otherwise, describe the problem as accurately and briefly as you can in the title. Keep the title short, please.

If you're describing a performance issue, be specific about your platform, network, message sizes, message rates, etc.

Here are various things you can do to simplify work for other people. Remember that if you can reproduce an issue, you have already a large advantage over others.

  • Test on older versions of libzmq to see if it is a regression.
  • Test on different platforms to see if it is system-specific.
  • Create a stripped-down C-only test case that reproduces the issue, the simpler the better.

And then in your issue, explain clearly, and without decoration:

  • The problem you're seeing, which should be the title of the issue.
  • The operating system you're on and perhaps some information about the hardware.
  • The version of the software you're using.
  • A brief description of the problem.
  • A more detailed explanation of how to reproduce it.
  • A minimal test case.

How do I test my issue?

The art in hunting and killing an issue, dead, is to create a minimal test case that reproduces the issue reliably, explicitly, and without any doubt. You want to avoid any extraneous functionality or libraries or anything that distracts from the issue. If it really is a ØMQ issue, it is by experience reproducible in a 100-line test case in C. If you can't write that, other people will help here.

Often, you will want to start several ØMQ peers and create the appropriate socket flows between them, to provoke your issue. This is easiest done as a single process, with threads for each peer. This lets you start the threads precisely as needed to recreate the issue. Your goal is to get the crash, or failure condition, as systematically as possible.

Where do I put the test case?

We then need to make the same test case in C, to avoid any possibility that the language binding is at fault. We also like to make the test case work with all current branches of libzmq (e.g. 2.x and 3.x). To keep test cases in one place, we have a single github repository for issues.

Clone this repository, add your test cases, and make a pull request. We'll then merge your test case, retest, and take over the work.

Who tracks the bug?

You do. We don't have project managers. Each user who finds an issue is responsible for convincing others that the issue is real, providing test cases, and following the fix into a released branch or package. This sounds like a lot of work but experience tells us that it's quite doable for all. It also has the great benefit that if you report an issue, you get to confirm the final fix.

Backporting to older stable releases

Someone may backport a fix to older releases but the best is that you, as 'owner' of an issue, ensure it gets properly backported so you can test on a stable release. Ask if you need help for this.