Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Home

seancribbs edited this page · 2 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
  • Java code/package generation via Maven
  • Python code/package generation via setuptools (requires protoc to be present)

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. For these reasons, as of March 2013 (Riak 1.4 development cycle), we are instituting a new policy that we hope will help alleviate these issues.

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.

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)
Something went wrong with that request. Please try again.