I would like to know your ideas regarding marking APIs for removal and documenting since when API is deprecated. @Andreas_Klein created a PR that adds or extends deprecation annotations and javadocs in this PR, and I need your input here.
We have inherited a lot of API that has been already marked deprecated. In some cases deprecated methods or classes have a documentation what is the replacement for it, in many cases we do not have that information.
So far I have marked API with
@Deprecated(forRemoval=true)
when the deprecated API has a known replacement. We do not remove such API with 1.0, but we will remove somewhere in the future. When excactly is to be discussed.
The PR marks every inherited deprecated API for removal, and I would like to object against that. We do not know the intention of deprecations yet, but I think such API we need to decide on a case-by-case level if we mark them for removal.
The next open question in the PR is when and how to add the āsinceā information to @Deprecation annotations. The PR proposes to use since="1.0.0-beta-1" for such inherited deprecated API. Technically it is true that ā1.0.0-beta-1ā was the first release since when such API is deprecated in Operaton. IMO we should use only the minor release level for the since information. I.e. I would mark these APIs with deprecated since ā1.0ā. This will be the first production release since when the API is actually deprecated. And for the future, I would like to argue that further deprecations would require a minor release. I would not expect new deprecations on a patch version level.
A next question is how and where we document new deprecations and to decide when certain API is planned to be removed. Would removal be done with the 2.0 version the next time, or is there also a possibility to remove API in 1.x?
What are your thoughts?
+1 for deprecation version = 1.0 meaning first possible version where something could be changed is 1.1.
And +1 that we add āfor removalā only if we know (and add to the Java docs) the replacement usage.
This way it is a pretty clear process as a user: Check your code for deprecations and use the documented replacement.
2 Likes
Iād support both recommended approaches here:
- Deprecations start from minor releases (maybe
1.0.0 instead of 1.0 as there never was a release 1.0 and never will be?)
Iām not quite sure about only adding āforRemovalā of we know of a replacement usage. If there is no replacement, why would it be deprecated? What would the users be expected to do here?
2 Likes
At least we can say as long as we donāt have a documented replacement, we will not remove this function. We inherited these deprecations, i think Karsten is right that we have to go through them individually. For some reason they were marked as deprecated.
If we use 1.0 or 1.0.0 as version: i think it could be better to have the exact version but never remove it within the same minor version.
Users should be aware that these methods are considered potential removal candidates in the future. The methods should not be in use. The features they represent might be outdated. We do not know that for sure right now. The usage of these methods is still safe, though. Methods marked like this should be evaluated case by case and we might then come to the conclusion that they have to be removed in the future. For that case we mark them as āforRemovalā, and this is a strong signal to users that they have to expect that these methods will be removed.
We have to communicate the removal of methods and classes that have been marked for removal in advance. They will not silently disappear with a next release. We have to document somewhere, when removal is actually planned.
Letās say we plan to come up with a version 2.0. Removal of API is actually a breaking change, thus removal would be safe in such a version. Then we communicate on a list somewhere which API is planned for removal and document that it will be removed for 2.0.
We might come to the conclusion that we want to keep a 1.x stream for a longer time. Usually API removal is not valid in minor version increments. But keeping this API forever also not. We could for this case follow the policy from Eclipse Platform. The current versions of many plugins wonāt move to a major increment, but usually increment in minor versions. API removal is allowed there with a longer cadence. See this page how it is documented in Eclipse.
We should identify methods that have a replacement and mark them forRemoval.