ceph/src/arrow/docs/source/format/Versioning.rst

   1 .. Licensed to the Apache Software Foundation (ASF) under one
   2 .. or more contributor license agreements.  See the NOTICE file
   3 .. distributed with this work for additional information
   4 .. regarding copyright ownership.  The ASF licenses this file
   5 .. to you under the Apache License, Version 2.0 (the
   6 .. "License"); you may not use this file except in compliance
   7 .. with the License.  You may obtain a copy of the License at
   8
   9 ..   http://www.apache.org/licenses/LICENSE-2.0
  10
  11 .. Unless required by applicable law or agreed to in writing,
  12 .. software distributed under the License is distributed on an
  13 .. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  14 .. KIND, either express or implied.  See the License for the
  15 .. specific language governing permissions and limitations
  16 .. under the License.
  17
  18 Format Versioning and Stability
  19 ===============================
  20
  21 Starting with version 1.0.0, Apache Arrow utilizes
  22 **two versions** to describe each release of the project:
  23 the **Format Version** and the **Library Version**. Each Library
  24 Version has a corresponding Format Version, and multiple versions of
  25 the library may have the same format version. For example, library
  26 versions 2.0.0 and 3.0.0 may both track format version 1.0.0.
  27
  28 For library versions prior to 1.0.0, major releases may contain API
  29 changes. From 1.0.0 onward, we follow `Semantic Versioning
  30 <https://semver.org/>`_ with regards to communicating API changes. We
  31 expect most releases to be major library releases.
  32
  33 Backward Compatibility
  34 ----------------------
  35
  36 A newer versioned client library will be able to read any data and
  37 metadata produced by an older client library.
  38
  39 So long as the **major** format version is not changed, a newer
  40 library is backward compatible with an older library.
  41
  42 Forward Compatibility
  43 ---------------------
  44
  45 An older client library must be able to either read data generated
  46 from a new client library or detect that it cannot properly read the
  47 data.
  48
  49 An increase in the **minor** version of the format version, such as
  50 1.0.0 to 1.1.0, indicates that 1.1.0 contains new features not
  51 available in 1.0.0. So long as these features are not used (such as a
  52 new logical data type), forward compatibility is preserved.
  53
  54 Long-Term Stability
  55 -------------------
  56
  57 A change in the format major version (e.g. from 1.0.0 to 2.0.0)
  58 indicates a disruption to these compatibility guarantees in some way.
  59 We **do not expect** this to be a frequent occurrence.
  60 This would be an exceptional
  61 event and, should this come to pass, we would exercise caution in
  62 ensuring that production applications are not harmed.
  63
  64 Pre-1.0.0 Versions
  65 ------------------
  66
  67 We made no forward or backward compatibility guarantees for
  68 versions prior to 1.0.0. However, we made every effort to ensure
  69 that new clients can read serialized data produced by library version
  70 0.8.0 and onward.