netmq: version 3 lives in another repository, the flagship example is never closed, and the endian switch is mutually exclusive with ZeroMQ

Version 3 is a different repository under a different organisation

The versioning section explains that two versions are maintained, and then immediately hands one of them to somebody else.

Version 3 is described as the stable version, and version 4 as the same thing without obsolete code. A wiki page covers migrating between them, and both are published to the same package feed.

Then the sentence that matters for anyone crossing that line: this repository is for version 4, and for version 3 the reader is sent to a different repository, under a different organisation, with a different name.

That is a heavier boundary than a major version usually is. A consumer moving from 3 to 4 is not switching a version constraint, they are switching where the source comes from, which name the import root has, and which release tags they can pin. A fork of one cannot be merged with a fork of the other without reconciling two histories.

It also means the compatibility note below, which describes a break inside the 3.x line, applies to a codebase this repository does not contain.

The example at the centre of the README does not compile

There is exactly one code sample in this document, and it has two problems.

using (var server = new ResponseSocket("@tcp://localhost:5556")) // bind
using (var client = new RequestSocket(">tcp://localhost:5556"))  // connect

Those two lines are fine, and the address prefixes are the mechanism rather than decoration, which the next section covers. The problem is what comes after them.

The sample creates a response socket and a request socket in a using block, sends a frame from the client, receives it on the server, sends a reply back, and receives that. Then it stops. The using block is never closed, there is no closing brace, and the final statement ends without a semicolon.

So the one piece of executable documentation in the README does not compile, which is worth knowing before you copy it. The rest of the sample is a faithful request and response round trip, so the fix is two characters rather than a rewrite.

It is also the only place a reader sees what a socket looks like. Everything else in the file is prose or a link, so the sample carries the entire conceptual weight of the introduction.

Bind and connect are the same string with a different first character

The example encodes which side of the connection a socket takes in the address itself, which is the single most surprising thing about this API for someone arriving from a socket library that separates the two.

An at sign in front of the protocol means bind, and a greater-than sign means connect. The server in the sample takes one address, the client takes the other, and both point at the same host and port.

That design has a practical consequence that the introduction hints at rather than states: a bind address and a connect address are not interchangeable strings, so the same endpoint has two spellings, and swapping them silently changes which side of the socket pair you are on. In a deployment where configuration is templated, that is the kind of error that produces a socket that connects successfully to nothing.

It also explains why the transport story is described as seamless access to multiple transport protocols. The protocol prefix is part of the same address string that carries the bind or connect role, so changing either is an edit to one value.

The compatibility switch lets you reach old peers or ZeroMQ, never both

One note in this README is longer and more consequential than the introduction, and it is about a decision that cannot be dodged.

Since version 3.3.07, number serialization changed from little endian to big endian in order to be compatible with ZeroMQ. Any NetMQ version prior to 3.3.0.7 is not compatible with the new version.

There is a way to support older peers: set the Endian option on a NetMQ socket to little endian. The same sentence then says that doing so makes it incompatible with ZeroMQ. So the option does not restore compatibility across the board, it moves the incompatibility from old NetMQ peers to every ZeroMQ implementation on the network.

The recommendation follows: update to the latest version and use big endian, which is now the default.

Two details in that section are worth noting. The version is written two ways, as 3.3.07 in the first sentence and 3.3.0.7 in the second, so anyone scripting a version check has to guess which form is canonical. And the note sits at the bottom of the file, after the consulting table, where a wire format break of this kind is unlikely to be found.

The documentation is one guide, one volunteer's site, and a 2014 blog series

The documentation section is a list of links, and the links have different vintages.

The instruction comes first: before using NetMQ, make sure to read the ZeroMQ Guide. That is a deliberate delegation, since NetMQ is a port and its intended audience is assumed to already know the protocol it implements.

Then the NetMQ documentation itself, hosted on Read the Docs, with a credit to a named individual who agreed to do the documentation. That credit tells you the documentation is a single person's work rather than a team effort, which matters when you are evaluating whether it will be kept current.

Samples live in yet another repository, and the blog links are a mix of one contributor's category page and six posts from a single blog, all dated August and September 2014. The series is numbered, and the numbering is not quite complete: the posts run from a first introduction through a second on socket types, a third on socket options, a fourth on multiple socket polling, then an unnumbered post on sending from multiple sockets, and then a sixth on divide and conquer. Number five is missing and one post has no number at all.

Two continuous integration systems are configured at once

The root of the repository contains configuration for two build systems, and only one of them is current.

The badge at the top of the README points at a GitHub Actions workflow, and there is a .github directory behind it.

Beside that, an appveyor.yml file sits in the root. AppVeyor is the older hosted Windows build service, and its configuration has outlived the migration. The tree carries codecov.yml as well, so coverage reporting was configured for both systems.

This is the same pattern most repositories reach after changing CI providers: the new configuration is added, the old one stays because deleting it was never urgent. It costs nothing at build time and it does cost a reader, because a file in the root is a claim that something still depends on it.

The rest of the root is documentation-shaped. There is a .readthedocs.yml beside an mkdocs.yml, so the Read the Docs site is built with MkDocs from the docs directory. AUTHORS.md and CONTRIBUTING.md both sit next to README.md, which means the contribution rules exist in two places.

Coding standards are prose, and the process is a named specification

The contributing section is short and specific, and it duplicates a file in the root.

Process first: the project uses the C4.1 process, linked to a specification in the ZeroMQ RFC archive, and the instruction is to read it before contributing. The ownership section repeats the same instruction, so the requirement appears twice.

Standards next, and they are precise: C# styles, camelCase for variables and fields with an m_ prefix for instance members and an s_ prefix for static fields, PascalCase for methods, classes, and constants. Then two settings arrive in one garbled clause, asking the reader to use Insert Spaces and 4 for tab and indent size.

None of that is backed by a configuration file. There is no editor configuration file in the root listing, so the naming convention and the indentation rule exist only as sentences, and the naming convention in particular is the kind of thing a linter would enforce.

Three further ways to help are offered: join the mailing list and be active in it, write tutorials in the wiki, and write about the project in your own blog and open a pull request adding a link at the bottom of the README. That last one is why the blog series and the support table below it grow over time.

Support is a table with one row, naming the founder and maintainer, and one instruction: if you provide support or consulting, add yourself by pull request.

Editorial conclusion

Use NetMQ when you want ZeroMQ's socket model in C# and you are starting a new project, since the default big endian behaviour is what interoperates with every other ZeroMQ implementation. Read the compatibility note before you upgrade anything, because the only way to talk to a pre-3.3 peer is to give up ZeroMQ compatibility, and that trade is not available on a mixed network. And plan your repository boundary now: the previous major version is not a branch of this one, it is a different project under a different organisation, so an upgrade across it is a migration of sources as well as packages.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. zeromq/netmq on GitHub