+1 for the proposed policy, and the list looks good to me as well. The minor 
version deprecations required category is indeed what most end application 
users I see depend on directly.

Best,
Jack Ye

From: Daniel Weeks <dwe...@apache.org>
Reply-To: "dev@iceberg.apache.org" <dev@iceberg.apache.org>
Date: Wednesday, September 28, 2022 at 4:18 PM
To: Iceberg Dev List <dev@iceberg.apache.org>
Subject: [EXTERNAL] [DISCUSS] Semantic Versioning Guarantees post 1.0

Hey Iceberg Community,

I wanted to raise a discussion thread with respect to how to handle semantic 
versioning and deprecations so that we can document the expectations for 
changes to the baseline going forward.

The goal is to clarify/formalize for users, contributors, and reviewers the 
expectations around changes to Iceberg public facing interfaces and what that 
means in context of the 1.0 release and future releases.

Prior to 1.0, there has been an informal policy that all public facing APIs 
require deprecation and backwards compatibility for at least one minor release. 
 Earlier discussion around the 1.0 release included stronger major version 
guarantees for the iceberg-api module and Revapi was introduced with the intent 
to enforce additional major version guarantees.  Those interfaces are the 
primary set that Iceberg users interface with and minor version changes could 
be disruptive.

However, this still leaves a large portion of the codebase without a clear 
designation of what is "publicly facing" and what is considered "internal".  
During the community sync today, a few different approaches were discussed but 
it sounded like there was some support for the proposed policy below.  The 
expectation being that some of the central modules would require a deprecation 
cycle to ensure stronger guarantees while other modules that are less likely to 
have direct dependencies would still err toward deprecations, but if more 
significant structural changes are necessary or solutions are difficult to 
incorporate without breaking changes, it would be up to the discretion of 
reviewers/committers to allow breaking changes.

I've also included some other ideas that are more strict or more flexible as 
alternatives.

Please share support, objections, or alternatives that you think clarify the 
approach going forward.

Proposed Policy:

Major Version Deprecations Required
iceberg-api module

Minor Version Deprecations Required
iceberg-common
iceberg-core
iceberg-parquet
iceberg-orc

Minor Version Deprecations Discretionary
(all modules not referenced above)

Alternatives:

  1.  Formalize current policy

     *   Minor version guarantees only
     *   No major version guarantees

  1.  Strict policy

     *   Major version guarantees for iceberg-api module
     *   Minor version guarantees for all other modules
     *   Strongest guarantees, least flexible

  1.  Discretionary Policy

     *   Major version for iceberg-api
     *   Discretionary for other modules
     *   Most flexible, weaker guarantees

  1.  Annotation driven policy

     *   Experimental/Stable/etc. annotations denote policy at a 
class/interface-level
     *   Most granular, difficult to implement/maintain
-Dan

Reply via email to