Changing the Apache Arrow Format Specification¶
Cross-language compatibility is important in Apache Arrow. To maintain it, we use the following process when dealing with changes to the format (files in https://github.com/apache/arrow/tree/main/format):
We must discuss and vote on the changes on the public mailing list
We must have at least two reference implementations and associated integration tests
These do not have to be done in order. In most cases, having at least one draft reference implementation is helpful for design discussion.
Note
We must update the corresponding documentation (files in https://github.com/apache/arrow/tree/main/docs/source/format) 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 a
thread in dev@arrow.apache.org with the [DISCUSS] prefixed
subject.
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 can
start a vote for the format changes after we reach consensus in the
preceding 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 associated integration tests to confirm whether the format changes are compatible across languages and consistent.
Reference implementations must be within complete Arrow implementations. For example, the C++ library is acceptable but the Python 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. We may use Implementation Status to determine which implementations are complete.
Versioning¶
The format version (which is separate from the library versions) must also be incremented as new changed are made. See Format Versioning and Stability.