Changing the Apache Arrow Format Specification#

Cross-language compatibility is important in Apache Arrow. Tomaintain it, we use the following process when dealing with changes tothe format (files inapache/arrow):

  • We must discuss and vote on the changes on the public mailing list

  • We must have at least two reference implementations and associatedintegration tests

These do not have to be done in order. In most cases, having at leastone draft reference implementation is helpful for design discussion.

Note

We must update the corresponding documentation (files inapache/arrow)too.

Discussion and Voting Process#

Changes to the format should be discussed on the public mailing list.Anyone can join the discussion. The discussion should be started by athread indev@arrow.apache.org with the[DISCUSS] prefixedsubject.

Note

We sometimes use[Discuss],DISCUSS: or something similar but[DISCUSS] is recommended.

Here are some examples:

The voting process is used to verify we have reached consensus. We canstart a vote for the format changes after we reach consensus in thepreceding DISCUSS mailing list thread. Similar to discussion threads,voting thread must have the subject prefix[VOTE].

See also:Apache Voting Process

At Least Two Reference Implementations#

We must have at least two reference implementations and associatedintegration tests to confirm whether the format changes are compatibleacross languages and consistent.

Reference implementations must be within complete Arrowimplementations. For example, the C++ library is acceptable but thePython library is not, since it is a wrapper around the C++library. Here are candidate implementations:

  • The C++ implementation

  • The Java implementation

  • The Rust (arrow-rs) implementation

  • The Go implementation

We can discuss and vote to add more implementations to the list. Wemay useImplementation Status to determine which implementations arecomplete.

Versioning#

The format version (which is separate from the library versions) mustalso be incremented as new changed are made. SeeFormat Versioning and Stability.