zeromq

What counts as an issue?

Only bugs or clear design faults. We don't use the issue tracker for feature requests (it's pointless), design proposals (we use the wiki), patch tracking (we use github pull requests for most projects, and signed patches over email for libzmq), or questions (we use IRC or the email list).

How do I submit an issue?

First, check the existing open issues to be sure it's not a duplicate. Make sure you're running the latest version of the software (whether it's a stable or experimental branch), as we don't debug old versions.

Next, go to the core issue tracker and register, if it's the first time. Find the right component and create your issue. What we need is:

• 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 (if it's not obvious).
• A minimal test case, which we'll explain more about in a second.

What version of ØMQ do I test?

libzmq has two or more branches active at any time, usually an experimental one and a stable one. Issues may hit either of these branches, and most often will hit both. So ideally, test both branches. Otherwise, test the branch that's most important to you.

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.

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.