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
