Home

Luke Bakken edited this page Mar 1, 2017 · 11 revisions
Clone this wiki locally

riak_pb

This library is a central place for the specification of messages and protocol parameters used in Riak's Protocol Buffers client interface. It includes:

  • Message definitions, in src/*.proto
  • Erlang helper modules for encoding and decoding messages, in src/*.erl
  • C header file generation

Branching, tagging, and release strategy

Motivation

We recognize that the protocol specification is a linchpin a number of projects, including the Riak node, clients that use the generated code, and projects that extend the protocol for other purposes. As a result, it is possible for transitive dependencies on the library to conflict in certain situations. It is also important that the stated version of the library reflect the Riak release that it specifies.

Version scheme and dependencies

The version number of riak_pb will track the major/minor/patch version of Riak for which the messages are valid. Projects that depend on riak_pb should use tags, release packages, or version branches wherever possible. To facilitate forward movement of Riak development while maintaining stability of the protocol, an additional "tiny" version will be appended when new features are merged into the mainline for an upcoming release. For example, if new feature development is beginning for Riak 2.2 and protocol messages are needed, the first protocol feature that lands would cause the version to increment to "2.2.0.1". Subsequent features will increment to "2.2.0.2", "2.2.0.3", and so on.

As of riak_pb 2.3.0, the four-digit version is deprecated in favor of a semver-compatible scheme. Please see the compatibility document for information on which post-2.3.0 riak_pb versions are compatible with which Riak version.

This means that once the new messages and helpers pass code-review, the branches that implement the new feature can depend on that tag. During development, it might be sufficient to float on the 2.6 branch; more discussion here is needed. A final release may depend on a version that has a high "tiny" increment, but should always be pinned to a tag that exactly matches the major/minor of the release.

Version compatibility

To the greatest extent possible, messages from older Riak versions will continue to carry the same meaning with the newer protocol unless explicitly stated. This applies to patch releases of Riak as well: where the messages and helpers are unchanged between the first release and a patch release of Riak, the version of riak_pb will not be incremented.

Examples:

Server release Client/riak_pb version Compatible
1.3.1 1.3.0 TRUE - riak_pb version not incremented, no protocol changes
2.0.0 1.3.0 TRUE - but client might ignore some fields
1.3.0 1.4.1.1 FALSE - client can send unknown messages to server (which result in errors)

Branch discussions

Releases

Please use the release target to publish a release.