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?

[github-actions]

This issue has been automatically marked as stale because it has been open for 180 days with no activity. It will be closed in next 14 days if no further activity occurs. To permanently prevent this issue from being considered stale, add the label 'not-stale', but commenting on the issue is preferred when possible.

[github-actions]

This issue has been closed because it has not received any activity in the last 14 days since being marked as 'stale'