On depreciation and new unstable features - Defining a depreciation strategy #6758
Replies: 2 comments 2 replies
-
Thanks for starting this discussion @kienerj Changing default behavior of functionsI agree that, whenever possible, the RDKit should do the "right" ("best"?) thing by default. This may mean making changes to the code which result in "client" code (i.e. code which uses the RDKit) generating different results. We have done this in the past and will continue to do so; such changes get tagged with "Changes behavior" here in GitHub and are documented in the "Backwards incompatible changes" section of the ReleaseNotes.md document. I think this approach works and I don't recall complaints from the community about it. In the specific case of the tautomer hash and Deprecating/removing thingsYou're right that we should be more explicit about what the policy is. At the moment the release notes have sections for "Deprecated code (to be removed in a future release)" and "Code removed in this release", but we could make the list of deprecated items (and when they will be removed) more visible. @PatrickPenner did some work at the hackathon to make deprecations more visible. Hopefully that turns into a PR at some point. Marking new stuff as unstableThis is a good idea for features/additions where we aren't sure about the API (I don't think I'd want to automatically mark everything new as "unstable" though). There are already a few parts of the code where we mention that the API/results may change from release to release, but these are not easy to discover. Making things more discoverableI'm curious what others think the best way to make deprecations and "unstable" features visible is. Clearly we can (and will) continue to put things in the release notes (we can add as section to those for the unstable features), but it seems like it would be useful to have a place where this information is easily gathered in one place. Maybe in the GitHub wiki? Or perhaps a separate document in the repo itself? |
Beta Was this translation helpful? Give feedback.
-
For deprecations in Python there for now is a package that emulates the Java behavior of using So I think it will take a while to make this more easily available for developers (in python) directly without looking at some sort of documentation. maybe something similar exists in C++? (indeed |
Beta Was this translation helpful? Give feedback.
-
Nowadays I'm really more and more into the Software Engineering things than pure Cheminformatics. From my experience with the RDKit it is really missing a proper depreciation strategy to get rid of old crutch and be able to improve things. The crutch is also driven by new features that have issues and get improved over time but making the new versions only available via "version" or "feature" arguments to the method call or adding a new method with the versioning in the method name.
Currently the balance is way too much on the backwards compatibility-side.
As an example I want to use the RegistrationHash added in as far as I remember in 2022.9. This initial version has a severe issue with the tautomer hash removing double bond stereo, see here. In my opinion this makes it pretty much unusable. In 2023.3 this is fixed but only if you set the according feature flag:
Anyone wanting to use the in my opinion only actual working version of RegistrationHash must set this flag "for eternity".
It's hard to keep track of all the flags needed to get the intended version of the methods you are calling. In a final application, one must comment the code section to ensure nobody tries to remove the flag(s) and to explain why they need to be there.
My Proposal:
Define a depreciation strategy
Mark all new features as unstable
Very interested in the communities thought on this.
Beta Was this translation helpful? Give feedback.
All reactions