+1 to the approach outlined here. Thanks, Dan! On Wed, Sep 28, 2022 at 4:18 PM Daniel Weeks <dwe...@apache.org> wrote:
> 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 > 2. Strict policy > - Major version guarantees for iceberg-api module > - Minor version guarantees for all other modules > - Strongest guarantees, least flexible > 3. Discretionary Policy > - Major version for iceberg-api > - Discretionary for other modules > - Most flexible, weaker guarantees > 4. Annotation driven policy > - Experimental/Stable/etc. annotations denote policy at a > class/interface-level > - Most granular, difficult to implement/maintain > > -Dan > > -- Ryan Blue Tabular
