Document guidance on how to evaluate breaking API changes#20584
Open
alamb wants to merge 1 commit intoapache:mainfrom
Open
Document guidance on how to evaluate breaking API changes#20584alamb wants to merge 1 commit intoapache:mainfrom
alamb wants to merge 1 commit intoapache:mainfrom
Conversation
alamb
force-pushed
the
alamb/update_api_guidance
branch
from
70a3c2a to
2f15a2f
Compare
Contributor
Author
|
Thanks @goldmedal (nice to see you back!) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
Rationale for this change
DataFusion does make API changes from time to time, and that is a normal part of software development. However, it is important to evaluate the impact of those API changes on downstream users and to ensure that the benefits of the change are clear to those users.
I found a few times where API changes were made with the justification that "some APIs in DataFusion are cleaner" or "this is more consistent with other APIs". While those may be valid justifications, it is painful for downstream users who have change their code to accommodate the API change when they get nothing in return
This most recently happened in this PR
thus I think the contributor guide should include some guidance on how to evaluate breaking API changes and to ensure that the benefits of the change are clear to downstream users.
What changes are included in this PR?
Polish up the API guidance section
Are these changes tested?
By CI
Are there any user-facing changes?
Better / clearer docs