此文件記錄 Apache Hadoop 專案的相容性目標。列舉出影響 Hadoop 開發人員、下游專案和最終使用者的 Hadoop 版本之間的不同相容性類型。對於每種類型的相容性，此文件將
為了與先前版本保持相容性，所有 Hadoop 介面會根據目標受眾和穩定性分類。有關分類的詳細資訊，請參閱Hadoop 介面分類法。
本文件供 Hadoop 開發人員社群使用。本文件說明 Hadoop 專案變更的檢視方式。為了讓最終使用者和協力廠商開發人員對跨版本相容性有信心，開發人員社群必須確保開發工作符合這些政策。專案提交者有責任驗證所有變更是否維持相容性，或明確標示為不相容。
在元件內，Hadoop 開發人員可以自由使用私人和受限私人 API，但當使用不同模組的元件時，Hadoop 開發人員應遵循與協力廠商開發人員相同的準則：不要使用私人或受限私人（除非明確允許）介面，並在可能的情況下優先使用穩定介面，而非進化或不穩定介面。在不可能的情況下，建議的解決方案是擴充 API 的受眾，而不是引入或延續這些相容性準則的例外。在 Maven 模組內工作時，Hadoop 開發人員應盡可能遵守相同程度的約束，以使用位於其他 Maven 模組中的元件。
最重要的是，Hadoop 開發人員必須注意變更的影響。穩定介面不得在主要版本之間變更。進化介面不得在次要版本之間變更。新的類別和元件必須針對受眾和穩定性適當地標示。有關何時適當使用各種標籤的詳細資訊，請參閱Hadoop 介面分類法。一般來說，所有新的介面和 API 應具有最受限的標籤（例如私人不穩定），這不會妨礙介面或 API 的意圖。
本文件根據各種相容性考量分為數個區段。在每個區段中，引言文字會說明該區段中相容性的意義、其重要性以及支援相容性的意圖。隨後的「政策」區段接著以具體條款說明管理政策。
關鍵字「必須」、「不得」、「需要」、「應」、「不應」、「建議」、「不建議」、「推薦」、「可以」和「選擇性」應按照RFC 2119中所述解釋。
Java API 提供 @Deprecated 註解，將 API 元素標示為已標示為移除。註解的標準意義是 API 元素不應使用，且可能會在後續版本中移除。
在所有情況下，從 API 中移除元素都是不兼容的變更。元素的穩定性應決定何時允許此類變更。穩定元素必須在移除之前標記為已棄用，且不得在次要或維護版本中移除。演進中元素必須在移除之前標記為已棄用，且不得在維護版本中移除。不穩定元素可以在任何時候移除。如果可能，不穩定元素應在移除之前標記為已棄用至少一個版本。例如，如果方法在 Hadoop 2.8 中標記為已棄用，則在 Hadoop 4.0 之前無法移除。
穩定API 元素不得在標記為已棄用（透過 @Deprecated 註解或其他適當文件）之前移除，且必須標記為已棄用一個完整的主要版本。如果 API 元素在引入時標記為已棄用（表示它是預計移除的暫時措施），則 API 元素可以在下一個主要版本中移除。修改穩定API 時，開發人員應優先引入新的方法或端點，並棄用現有的方法或端點，而不是對方法或端點進行不兼容的變更。
開發人員應使用 @InterfaceAudience 和 @InterfaceStability 註解註解所有 Hadoop 介面和類別，以說明預期的受眾和穩定性。
註解可以在套件、類別或方法層級套用。如果方法沒有隱私或穩定性註解，則應從其所屬的類別繼承其預期的受眾或穩定性層級。如果類別沒有隱私或穩定性註解，則應從其所屬的套件繼承其預期的受眾或穩定性層級。如果套件沒有隱私或穩定性註解，則應假設其分別為私人和不穩定。
如果元素的受眾或穩定性註解與其父項目的對應註解（無論是明確或繼承）衝突，則元素的受眾或穩定性（分別）應由更具限制性的註解決定。例如，如果 私人 方法包含在 公共 類別中，則該方法應視為 私人。如果 公共 方法包含在 私人 類別中，則該方法應視為 私人。
相容性政策應由相關套件、類別或成員變數或方法註解決定。
注意：從 proto 檔案產生的 API 必須相容於滾動升級。請參閱有關線路協定相容性的章節以取得更多詳細資訊。因此，API 和線路協定的相容性政策必須相輔相成。
Apache Hadoop 致力於確保 API 的行為在各版本中保持一致，儘管為了正確性而進行的變更可能會導致行為變更。API 行為應由 JavaDoc API 文件（如果存在且完整）指定。當 JavaDoc API 文件不可用時，行為應由相關單元測試預期的行為指定。對於沒有 JavaDoc API 文件或單元測試涵蓋範圍的情況，預期的行為被假設為顯而易見，且應假設為介面命名所暗示的最小功能。社群正在更嚴格地指定某些 API，並增強測試套件以驗證是否符合規範，有效地為可以輕鬆測試的行為子集建立正式規範。
任何 API 的行為 MAY 根據 API 的穩定性而變更，以修正不正確的行為，此類變更將伴隨著更新現有文件和測試和/或新增文件或測試。
Apache Hadoop 修訂版本應保留二進位相容性，以便最終使用者應用程式繼續運作而無需任何修改。相同主要修訂版本內的次要 Apache Hadoop 修訂版本必須保留相容性，以便現有的 MapReduce 應用程式（例如最終使用者應用程式和 Apache Pig、Apache Hive 等專案）、現有的 YARN 應用程式（例如最終使用者應用程式和 Apache Spark、Apache Tez 等專案），以及直接存取 HDFS 的應用程式（例如最終使用者應用程式和 Apache HBase、Apache Flume 等專案）在與原始建置目標相同的任何 Apache Hadoop 群集一起使用時，無需修改且無需重新編譯即可運作。
特別是對於 MapReduce 應用程式，即使用 org.apache.hadoop.mapred 和/或 org.apache.hadoop.mapreduce API 的應用程式，開發人員社群應支援跨主要版本的二進位相容性。MapReduce API 應在主要版本間相容地支援。請參閱 Hadoop-1.x 和 hadoop-2.x 之間的 MapReduce 應用程式相容性 以取得更多詳細資訊。
某些應用程式可能會受到磁碟配置或其他內部變更的影響。請參閱後續各節，以了解如何處理與非 API 介面不相容的變更的政策。
Hadoop 包含數個原生元件，包括壓縮、容器執行器二進位檔和各種原生整合。這些原生元件會為 Hadoop 引入一組原生依賴項，包括編譯時和執行時，例如 cmake、gcc、zlib 等。這組原生依賴項是 Hadoop ABI 的一部分。
Hadoop 在編譯時間和/或執行時間依賴的原生元件的最低版本要求應被視為 Evolving。在主要版本中的次要版本之間，最低版本要求不應增加，儘管可能會因為安全問題、授權問題或其他原因而更新。當 Hadoop 所依賴的原生元件必須在主要版本中的次要版本之間更新時，如果可能，變更應只變更元件的次要版本，而不變更主要版本。
線路相容性涉及 Hadoop 程序之間「透過線路」傳輸的資料。Hadoop 使用 Protocol Buffers 進行大部分的 RPC 通訊。維護相容性需要禁止修改，如下所述。也應考慮非 RPC 通訊，例如使用 HTTP 傳輸 HDFS 映像作為快照的一部分或傳輸 MapReduce map 任務輸出。通訊可以分類如下
Apache Hadoop 的元件可能具有包括其自己的協定的相依性，例如 Zookeeper、S3、Kerberos 等。這些協定相依性應視為內部協定，並受相同政策規範。
除了協定的相容性之外，維持跨版本通訊需要支援的傳輸協定也必須穩定。傳輸協定變更最可能來自於安全傳輸協定，例如 SSL。將服務從 SSLv2 升級至 SSLv3 可能會中斷現有的 SSLv2 用戶端。在主要版本中的次要版本之間，任何傳輸協定的最低支援主要版本不應增加，儘管可能會因為安全性問題、授權問題或其他原因而更新。當傳輸協定必須在主要版本中的次要版本之間更新時，如果可能的話，變更應僅變更元件的次要版本，而不變更主要版本。
服務埠被視為傳輸機制的一部分。預設服務埠號碼必須保持一致，以防止中斷用戶端。
Hadoop 線路協定定義在 .proto（ProtocolBuffers）檔案中。用戶端伺服器和伺服器伺服器協定應根據其 .proto 檔案中註明的受眾和穩定性分類進行分類。在沒有分類的情況下，應假設協定為 私人 和 穩定。
對 .proto 檔案的下列變更應被視為相容
對 .proto 檔案的下列變更應被視為不相容
對 .proto 檔案的下列變更應被視為不相容
未透過 .proto 檔案定義的 Hadoop 線路協定應被視為 私人 和 穩定。
除了受限於 穩定 之外，Hadoop 的線路協定還必須根據以下規定，在主要版本中的次要版本之間向前相容：
新的傳輸機制只能在次要或主要版本變更時引入。現有的傳輸機制必須在主要版本中的次要版本之間持續支援。預設服務埠號應視為 穩定。
REST API 相容性適用於公開的 REST 端點（網址）和回應資料格式。Hadoop REST API 特別用於讓用戶端在各個版本（甚至主要版本）之間穩定使用。在本文件中，公開的 PEST API 是在公開文件中記載的 API。以下是公開 REST API 的非詳盡清單：
每個 API 都有特定於 API 的版本號碼。任何不相容的變更都必須增加 API 版本號碼。
公開的 Hadoop REST API 應視為 公開 且 演進中。關於 API 版本號，公開的 Hadoop REST API 應視為 公開 且 穩定，亦即不允許在 API 版本號內進行任何不相容的變更。REST API 版本必須標示為已棄用，才能在一個完整的重大版本中移除。
Hadoop 程式和 CLI 透過 Log4j 產生記錄輸出，旨在協助管理員和開發人員了解和排除叢集行為。記錄訊息旨在供人使用，但亦支援自動化使用案例。
多個元件具有稽核記錄系統，會以機器可讀取的格式記錄系統資訊。對該資料格式進行不相容的變更可能會中斷現有的自動化公用程式。對於稽核記錄，不相容的變更是指任何會變更格式的變更，使得現有的剖析器無法再剖析記錄。
雖然指標 API 相容性受 Java API 相容性規範，但 Hadoop 公開的指標資料格式必須維持與資料使用者的相容性，例如自動化工作。
使用者和系統層級資料（包括元資料）儲存在各種格式的檔案中。對用於儲存資料/元資料的元資料或檔案格式進行變更可能會導致版本之間不相容。每個檔案格式類別如下所述。
變更使用者用於儲存資料的格式可能會導致他們無法在後續版本中存取資料，因此相容性非常重要。這些格式的範例包括 har、war、SequenceFileFormat 等。
使用者層級檔案格式應視為 公開 且 穩定。使用者層級檔案格式變更應在主要版本間向前相容，且在主要版本內必須向前相容。開發人員社群應優先建立新的衍生檔案格式，而不是對現有檔案格式進行不相容的變更。此類新檔案格式必須建立為選擇加入，表示使用者必須能夠繼續使用現有的相容格式，直到且除非他們明確選擇加入使用新檔案格式。
Hadoop 內部資料也可能儲存在檔案或其他資料儲存中。變更這些資料儲存的架構可能會導致不相容性。
MapReduce 使用 I-File 等格式來儲存 MapReduce 特定的資料。
所有 MapReduce 內部檔案格式，例如 I-File 格式或工作歷程伺服器的 jhist 檔案格式，應視為 私人 且 穩定。
HDFS 以私人檔案格式保留元資料（映像和編輯記錄）。對格式或元資料進行不相容的變更會導致後續版本無法讀取舊元資料。不相容的變更必須包含一個處理程序，以便升級現有元資料。
根據變更的不相容程度，可能會出現下列潛在情境
HDFS 資料節點會將資料儲存在私人目錄結構中。對目錄結構進行不相容的變更可能會導致舊版本無法存取儲存的資料。不相容的變更必須包含一個處理程序，以便升級現有資料目錄。
HDFS 元數據格式應被視為 私人 和 不斷演進。不相容的變更必須包含一個程序，讓現有的元數據可以升級。升級程序應允許需要多次升級。升級程序必須允許群集元數據回滾到舊版本及其舊磁碟格式。回滾必須還原原始資料，但不需要還原已更新的資料。格式的任何不相容變更都必須導致架構的主要版本號碼遞增。
資料節點目錄格式應被視為 私人 和 不斷演進。不相容的變更必須包含一個程序，讓現有的資料目錄可以升級。升級程序應允許需要多次升級。升級程序必須允許資料目錄回滾到舊版配置。
S3Guard 元資料儲存庫用於在 DynamoDB 表格中儲存元數據；因此，它必須維持相容性策略。現在 S3Guard 已移除，這些表格不再需要。
設定為使用「null」儲存庫以外的 S3A 元數據儲存庫的應用程式將會失敗。
YARN 資源管理員會將群集狀態的資訊儲存在外部狀態儲存庫中，以用於故障轉移和復原。如果用於狀態儲存庫資料的架構無法保持相容性，資源管理員將無法復原其狀態，且無法啟動。狀態儲存庫資料架構包含一個版本號碼，用於表示相容性。
YARN 資源管理員狀態儲存庫資料架構應被視為 私人 和 不斷演進。架構的任何不相容變更都必須導致架構的主要版本號碼遞增。架構的任何相容變更都必須導致次要版本號碼遞增。
YARN 節點管理員會將節點狀態的資訊儲存在外部狀態儲存庫中，以用於復原。如果用於狀態儲存庫資料的架構無法保持相容性，節點管理員將無法復原其狀態，且無法啟動。狀態儲存庫資料架構包含一個版本號碼，用於表示相容性。
YARN 節點管理員狀態儲存庫資料架構應被視為 私人 和 不斷演進。架構的任何不相容變更都必須導致架構的主要版本號碼遞增。架構的任何相容變更都必須導致次要版本號碼遞增。
YARN 資源管理員聯合服務會將聯合叢集、執行中的應用程式和路由政策的資訊儲存在外部狀態儲存中，以供複製和復原使用。如果用於狀態儲存資料的架構無法保持相容性，聯合服務將無法初始化。狀態儲存資料架構包含一個版本號碼，用來表示相容性。
YARN 聯合服務狀態儲存資料架構應被視為 私人 和 演進中。任何與架構不相容的變更都必須導致架構的主要版本號碼增加。任何與架構相容的變更都必須導致次要版本號碼增加。
Hadoop 命令列程式可透過系統殼層或殼層指令碼直接使用。CLI 包含使用者導向的指令，例如 hdfs 指令或 yarn 指令，以及管理員導向的指令，例如用於啟動和停止守護程式的指令碼。變更指令的路徑、移除或重新命名命令列選項、變更引數順序，或變更指令回傳碼和輸出會破壞相容性，並對使用者造成負面影響。
除非記錄為實驗性質且可能會變更，否則所有 Hadoop CLI 路徑、用法和輸出都應被視為 公開 和 穩定。
請注意，CLI 輸出應被視為與 Hadoop CLI 所產生的記錄輸出不同。後者應受記錄輸出政策管制。另請注意，對於 CLI 輸出，所有變更都應被視為不相容的變更。
網頁介面，尤其是網頁的內容和配置，可能會干擾嘗試從網頁中擷取資訊的行為。然而，Hadoop 網頁介面頁面並非設計為可擷取，例如用於自動化的目的。預期使用者會使用 REST API 以程式化方式存取叢集資訊。
使用者依賴 Hadoop 叢集在不同版本間保持一致的行為。導致叢集出現意外不同行為的變更可能會造成挫折和漫長的採用週期。不應新增任何會變更現有叢集行為的設定，假設叢集的設定檔保持不變。對於任何定義的新設定，應小心確保新設定不會變更現有叢集的行為。
在同一次要版本內，維護版本之間的現有功能變更不得變更預設行為或現有組態設定的意義，不論變更是源自於系統或邏輯的變更，或是內部或外部預設組態值的變更。
在同一主要版本內，次要版本之間的現有功能變更不應變更預設行為或現有組態設定的意義，儘管變更（例如修正正確性或安全性問題）可能需要不相容的行為變更。在可能的情況下，此類行為變更應預設為關閉。
使用者使用 Hadoop 定義的屬性來組態並提供提示給 Hadoop，並使用自訂屬性將資訊傳遞給工作。建議使用者避免使用與 Hadoop 定義的屬性名稱空間衝突的自訂組態屬性名稱，並應避免使用 Hadoop 使用的任何前綴，例如 hadoop、io、ipc、fs、net、file、ftp、kfs、ha、file、dfs、mapred、mapreduce 和 yarn。
除了屬性檔案外，Hadoop 使用其他組態檔案來設定系統行為，例如公平排程器組態檔案或資源設定檔組態檔案。
Hadoop 定義的屬性（名稱和意義）應被視為 公開 和 穩定。Hadoop 定義的屬性所暗示的單位不得變更，即使跨主要版本也是如此。Hadoop 定義的屬性的預設值應被視為 公開 和 演進中。
不受上述有關 Hadoop 定義的屬性規則約束的 Hadoop 組態檔案應被視為 公開 和 穩定。不相容變更的定義取決於特定的組態檔案格式，但一般規則是相容的變更將允許在變更前有效的組態檔案在變更後仍然有效。
Hadoop 程式和 CLI 產生的記錄輸出是由一組組態檔案所控制。這些檔案控制 Hadoop 各個元件將輸出的記錄訊息的最低層級，以及這些訊息的儲存位置和方式。
原始碼、人工製品（原始碼和測試）、使用者記錄、組態檔案、輸出和工作記錄都儲存在本機檔案系統或 HDFS 上的磁碟中。變更這些使用者可存取檔案的目錄結構可能會破壞相容性，即使在透過符號連結保留原始路徑的情況下也是如此（例如路徑是由設定為不遵循符號連結的 servlet 存取時）。
原始碼和建置人工製品的配置應被視為 私人 和 不穩定。在主要版本中，開發人員社群應保留整體目錄結構，儘管個別檔案可以在沒有警告的情況下新增、移動或刪除。
Hadoop 提供多個用戶端人工製品，供應用程式用來與系統互動。這些人工製品通常會對常見的函式庫有自己的相依性。在這些相依性公開給最終使用者應用程式或下游使用者（例如，未遮蔽）的情況下，對這些相依性的變更可能會造成中斷。強烈建議開發人員使用遮蔽等技術，避免將相依性公開給用戶端。
關於相依性，新增相依性是不相容的變更，而移除相依性則是相容的變更。
某些針對 Hadoop 建置的使用者應用程式可能會將所有 Hadoop JAR 檔案（包括 Hadoop 的函式庫相依性）新增到應用程式的類別路徑。新增新的相依性或更新現有相依性的版本可能會干擾應用程式類別路徑中的相依性，進而影響其正確的運作。因此，不建議使用者採用此做法。
Hadoop 用戶端人工製品公開的相依性集合應被視為公開且穩定的。任何未公開給用戶端的相依性（因為它們已遮蔽或只存在於非用戶端人工製品中）應被視為私有的且不穩定的。
使用者和相關專案通常會使用 Hadoop 輸出的環境變數（例如 HADOOP_CONF_DIR）。因此，移除或重新命名環境變數可能會影響最終使用者應用程式。
Hadoop 使用的環境變數，以及透過 YARN 提供給應用程式的環境變數應被視為公開且持續演進的。開發人員社群應將變更限制在主要版本中。
Hadoop 使用 Maven 進行專案管理。對已產生人工製品的內容進行變更可能會影響現有的使用者應用程式。
Hadoop 測試人工製品的內容應被視為 私人 且 不穩定。測試人工製品包括從測試原始碼產生的所有 JAR 檔案，以及檔名中包含「測試」的所有 JAR 檔案。
Hadoop 用戶端人工製品應被視為 公開 且 穩定。用戶端人工製品如下
為了跟上硬體、作業系統、JVM 和其他軟體的最新進展，新的 Hadoop 版本可能會包含需要比先前 Hadoop 版本更新的硬體、作業系統版本或 JVM 版本的功能。對於特定環境，升級 Hadoop 可能需要升級其他依賴的軟體元件。
以下是與此主題相關的一些 JIRA 和頁面