A more robust way to deprecate APIs

[ndrluis]

Feature Request / Improvement

I was studying Python libraries and how they handle deprecation. Specifically, I was exploring constant deprecation in the context of issue #1217. I found this module in Conda, and they have good documentation about deprecation. Since BSD-3 is compatible with Apache 2.0, I believe we could adopt their approach to deprecation. It is more robust and provides the ability to deprecate constants in a module or arguments in a function.

I’d love to hear what you all think about this. Are there any suggestions or concerns we should consider?

[kevinjqliu]

thanks for doing the research! I like this approach. it seems more robust than our current one.
do you know if the deprecation message includes the call site or stack trace? for example, in #1336, it would be helpful to know which function produced the deprecation message

[Fokko]

Hey @ndrluis thanks for bringing this up! Are you suggesting to copy the code into our codebase? I always favor reusing an existing library instead of reinventing the wheel. I also noticed that they refer to deprecation in the code, which might also be a good candidate.

[ndrluis]

@kevinjqliu Yes, it refers to the call site. The ‘argparse.Action’ example in the documentation demonstrates this.

@Fokko I agree with using a library, but the deprecation library has fewer features than conda.deprecation. One of the most important features I am looking for is the constant deprecation that exists in Conda. I think that, in our case, it makes more sense to copy the deprecation source code from the Conda codebase rather than having Conda as a dependency.

[Fokko]

My concern is that I don't see conda on pypi, and we don't want to force users to condaforge.

If the license is compatible, we can also copy the code, and mention it in the LICENSE:

iceberg-python/LICENSE

Line 225 in 7a83695

--------------------------------------------------------------------------------

[ndrluis]

One new aspect introduced with this Conda deprecation code is the concept of a pending deprecation process. I think that when we release version 1.0, we will need to allocate more time to remove deprecated code. The idea is to establish a timeline for pending deprecations, during which users can dispute the decision to deprecate a specific API. I believe this is a valuable feature, as we already have a relevant example in issue #1104.

More details about the Conda deprecation policy are available here: https://github.com/conda/ceps/blob/main/cep-0009.md.

I plan to add a section to our documentation about the deprecation policy, following the guidelines outlined here: https://iceberg.apache.org/contribute/?h=deprecation#major-version-deprecations-required.

What do you all think?