Too Many Stable API Changes With Each Update

[mildroid]

Hi there,
I just wanted to say that I really enjoy using your library. The implementation is great, and the animations are really smooth.
However, I have noticed that there are too many stable API changes with each update. This forces to change the code and implementations every time we update the library.
For example, in the most recent update (1.7.2), I received an "IllegalArgumentException: Cannot round NaN value" With exactly same entries that worked perfectly fine in the previous version.
I understand that you need to make changes to the library to improve it, but I would appreciate it if you could try to make the API changes more stable.

Thanks for your time

[p-fischer]

Hi. I really appreciate your library and the work you put into it. Great job!

I'm backing up this request. I recently introduced this library using version 1.6.5 and was very suprised that updating to 1.6.6. introduced breaking changes.

As a consumer of this library it would be tremendously helpful if you would stick to semantic versioning and only introduced breaking API changes with major versions.

My second request would be that breaking changes were easily recognizable in the release notes. I haven't updated to 1.7.2 yet but the release note sections "Additions" and "Improvements" would have let me believe there are no breaking changes.

The amount of breaking changes I saw in the last 2 months (1.6.5 - 1.7.2) is getting me worried because I hoped to use this library in my app for years. Currently, it looks like this library was higher maintenance than all other libraries combined. I hope as - the library matures - less API changes will be necessary.

[patrickmichalik]

Hello! I’d like to preface by making two remarks. First, we understand that breaking changes are an inconvenience, and we do our best to avoid introducing such changes. Second, the number of significant API changes introduced recently certainly isn’t what we expect to be the usual. The updates that you’re seeing are the result of our rethinking of several core APIs to introduce features that have been requested over the past year. Vico is at a relatively early stage of development, and since its initial release, we’ve learnt a lot about how people expect it to work and what use cases they’re looking to apply it to.

Regarding Semantic Versioning, while we agree that it can be of great utility, if we were to follow it strictly, either the library’s development would be quite significantly impeded, or we’d be at version 10 or so by now. Once again, we’ll be doing our best to keep large API changes to a minimum, but sometimes, they are effectively unavoidable. Take version 1.6.6, which you’ve mentioned. It was requested that a chartValues parameter be added to MarkerLabelFormatter#getLabel, and we had no other choice than to introduce a breaking change. Going from 1.6.5 to 2.0.0 for a single parameter would, we believe, be a bit excessive, so we increment the version number based on the general significance of an update. I believe Google takes a similar approach with Jetpack Compose.

That said, we do our best to make it clear when API changes are introduced. Here’s an excerpt from the release notes for Vico 1.6.6:

MarkerLabelFormatter#getLabel now has a chartValues parameter. Because MarkerLabelFormatter is a functional interface, deprecation was impossible—this a breaking change.

We also mention when APIs are deprecated. This is from the 1.7.2 release notes:

HorizontalAxis and all HorizontalAxis-creating APIs now have itemPlacer fields and parameters, and their labelOffset and labelSpacing fields and parameters are deprecated.

Please feel free to share suggestions regarding how we could better warn users of breaking changes and deprecations in the release notes. Perhaps setting the relevant phrases in bold, as I have done here, would help?

Regarding version 1.7.2, I wanted to clarify that the problem described above is a bug, not a breaking change. @mildroid has created a bug report, and we’ll get to work on a hotfix as soon as we have all the required information.

Finally, I’d like to note that if you ever have any doubts about how to handle a Vico update, you’re more than welcome to create a discussion. We’ll be happy to help you out.

We appreciate your feedback. Thank you for sticking with us.

[p-fischer]

Thanks, I really appreciate your quick and thorough answer and thanks for sharing your thoughts!

I agree the development of the library shouldn't be held back by semantic versioning. How about a compromise to only add breaking changes in major or minor updates? I'd say I generally read minor version release notes while I tend to blindly update patch version updates.

You're right, breaking API changes are mentioned in the release note texts.
Taking version 1.7.2 as an example, initially I tend to quickly scan the release note sections, which in this case are "Additions" and "Improvements". Grouping all breaking changes under a separate section would highlight these most critical changes.

Here's a release notes example from androidx.compose.
They're using section names "API Changes" and also "Behavior Changes", which I both find very intuitive.

I really appreciate that you're so open to suggestions!

[patrickmichalik]

Thanks for the suggestions! I like the idea of keeping patch releases free from breaking changes but allowing such changes when either the major version number or the minor version number is incremented. We’ll adopt this approach.

Regarding the release notes, we actually used to have an “API changes” section. I shifted away from it because, when one API replaced another, I found myself trying to describe the change under both “Additions” (for the new API) and “API changes” (for the API being replaced). But now that I think of it, we can take a more pragmatic approach and reserve “Additions” for new APIs that don’t replace anything, while using the “API changes” section for changes where API replacement occurs. How does that sound to you?

[p-fischer]

Sounds excellent 👍 Thanks 🙂

[patrickmichalik]

I’m glad to hear that. We’ll use this approach, then. Thanks again for all your input!

[patrickmichalik]

Hello! I’m sorry to hear that you’re seeing such an error. This isn’t an intentional API change, but rather a bug, for which we apologize. Could you provide a minimal reproducible example? We’ll then be able to publish a hotfix.

To address your concern more generally, we try to make updating from one Vico version to the next as straightforward as we can, but many key improvements would be impossible to implement without the deprecation of certain APIs. Because the issue that you’ve described is a bug, not an API change as such, we’d appreciate it if you could provide one or two other examples of recent changes that you found problematic. Thank you!

[mildroid]

Thank you for your response. I appreciate you taking the time to investigate this case.
I agree that the bug I reported was not a good example of a stable API change. I apologize for the confusion.

I believe that it would be beneficial to make stable API changes less major. This would make the library more reliable in the long term use.
Also I found @p-fischer 's comment about the versioning helepful.

Overall, my purpose is to help Vico get better and more reliable. I just really like it.
Thank you for your time and consideration.

[patrickmichalik]

No worries about the example. We appreciate the bug report. Let me refer you to my reply to @p-fischer, which you can find here. I’ve addressed the API-related concerns at length there. Please feel free to share any further feedback you may have.