API Deprecation and Removal Policy Revision 1 #474
Replies: 5 comments 19 replies
-
|
👍 Two comments:
|
Beta Was this translation helpful? Give feedback.
-
How about "should be avoided in patch releases"? The one use case I have in mind is, if one would forget a deprecation in a major/minor release. To fix such an oversight with a minor release that only adds a deprecation (which might be a release notes only change in some cases 😅) feels strange, no?
@ktf I basically took the two weeks from your feedback earlier today. I would be fine with two months as well, any objections? |
Beta Was this translation helpful? Give feedback.
-
Looking from the alternative API (if there is one…) side of things: |
Beta Was this translation helpful? Give feedback.
-
To me deprecation is on a similar level as feature additions. Both really shouldn't happen in patch releases. If you forgot a feature in a minor release you wouldn't add it in a patch release either. Right? |
Beta Was this translation helpful? Give feedback.
-
After sleeping on it, I agree with this argument - deprecation is still a bit weaker compared to an addition, since it is not the removal yet, but it is also clearly not a bug fix which is meant to be represented by the patch version according to the semver definition. And it will go along with @ChristianTackeGSI's comment as well. |
Beta Was this translation helpful? Give feedback.
-
Then two months it is. |
Beta Was this translation helpful? Give feedback.
-
|
Personally, I think this is to much of "legal" wording. To me the whole behaviour I would want can be summarised by: "Two SUBSEQUENT releases SHOULD not introduce any warnings or errors in dependent codebases (e.g. O2) unless an alternative, equivalent solution working in both is provided." For the definition of SUBSEQUENT. For me is anything which happens between one validation at point 2 and the other, but if you prefer to put two months, that's also fine. Of course exceptions are possible when doing things incrementally creates more work than it saves, it does not need to be strict. |
Beta Was this translation helpful? Give feedback.
-
Yes. If I opt in to getting diagnostics about deprecations in dependencies, then I'm interested in porting away from deprecated API and would be extremely unhappy if I get no warnings for deprecated APIs. However if I'm not the one to do the work and another person decided I must turn on those warnings, yes I'd be annoyed. But who does that...? |
Beta Was this translation helpful? Give feedback.
-
|
Anyone who has a running experiment and needs to support a two versions of your software for a few weeks to allow quick rollback in case there are troubles, without having to worry about unrolling cosmetic changes (which in the meanwhile might interfere with the over 100 commits per week we get to our codebase). Yes, I could temporarily turn off |
Beta Was this translation helpful? Give feedback.
-
What I interpret into this request is actually that you would like FairMQ being tightly integrated into the O2 codebase/development model like another module in O2. Then any change would naturally follow the downstream schedule and coordination and all this overhead of doing separate releases and supporting multiple upstream APIs would immediately be gone. I am very open to looking into such an option, tbh. But as long as we keep FairMQ as a separate project/library, it is a different story, is it not? |
Beta Was this translation helpful? Give feedback.
-
|
No, that's not what I asked. I guess I forgot a "kindly" and it should have been "As your client I am kindly asking". I think @ChristianTackeGSI explained very well the need: if something triggers a lot of deprecation warnings in many places, please, be pragmatic and hold for a bit adding [[deprecated]]. You can still deprecate it in words in the release notes. It will make the experience of your users smoother and no one in your audience will miss the extra warnings for a couple of weeks. Regarding the integration, I think we did well so far, I frankly do not see why to change. |
Beta Was this translation helpful? Give feedback.
-
Your request as understood by upstream:
Downsides for upstream if implemented as requested:
Upstream thinks the pre-announcing deprecating release is unnecessarily complicating its release process and provides a counter offer:
Upstream understands your use case, it is implemented like this:
--- a/fairmq.sh
+++ b/fairmq.sh
@@ -1,6 +1,6 @@
package: FairMQ
-version: "%(tag_basename)s"
-tag: v1.5.0
+version: "%(tag_basename)s-alice"
+tag: v1.6.0
source: https://github.com/FairRootGroup/FairMQ
requires:
- boost
@@ -35,7 +35,7 @@ esac
cmake "${SOURCEDIR}" \
-GNinja \
- -DFAIRMQ_NO_DEPRECATED_DECLARATIONS=OFF \
+ -DFAIRMQ_NO_DEPRECATED_DECLARATIONS=ON \
${CXXSTD:+-DCMAKE_CXX_STANDARD=${CXXSTD}} \
${CXX_COMPILER:+-DCMAKE_CXX_COMPILER=${CXX_COMPILER}} \
${CMAKE_BUILD_TYPE:+-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}} \
--- a/fairmq.sh
+++ b/fairmq.sh
@@ -1,5 +1,5 @@
package: FairMQ
-version: "%(tag_basename)s-alice"
+version: "%(tag_basename)s"
tag: v1.6.0
source: https://github.com/FairRootGroup/FairMQ
requires:
@@ -35,7 +35,7 @@ esac
cmake "${SOURCEDIR}" \
-GNinja \
- -DFAIRMQ_NO_DEPRECATED_DECLARATIONS=ON \
+ -DFAIRMQ_NO_DEPRECATED_DECLARATIONS=OFF \
${CXXSTD:+-DCMAKE_CXX_STANDARD=${CXXSTD}} \
${CXX_COMPILER:+-DCMAKE_CXX_COMPILER=${CXX_COMPILER}} \
${CMAKE_BUILD_TYPE:+-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}} \Upsides for upstream:
Upsides for downstream:
Downsides for downstream:
And as we discussed in the other threads and as it is already stated in the proposed policy, there are exceptions to the above, the two most important that come to mind are:
|
Beta Was this translation helpful? Give feedback.
-
|
I fully agree with @dennisklein 's proposal @mattkretz 's comment.
|
Beta Was this translation helpful? Give feedback.
-
Ok, that would be more strictly the semver definition. Let's adopt that. Will take a bit of getting used to it, since we underused major and minor versions in the past years. but that was broken anyways ;)
Following @mattkretz's definition deprecation is similar to feature addition, and it is clearly not breaking. From that I conclude deprecation can happen in minor releases as well, which you don't deny, but what is the specific reason you feel it should be preferred in major releases? |
Beta Was this translation helpful? Give feedback.
-
The removal point is clear, but for deprecation there are two cases: Can the compiler warning be reasonably filtered out by downstream? |
Beta Was this translation helpful? Give feedback.
-
|
I agree about removals only in major versions. The point of major versions is to ship breaking changes. But deprecation of API happens whenever replacement is ready. No need to hold back useful information. If the intent is to remove, then make it clear. Deprecation in minor releases (feature releases) should be fine. |
Beta Was this translation helpful? Give feedback.
-
|
One other point is the (potential) amount of code downstream ("customer") has to touch. If it's a few lines of code (< 10 warnings), then things are different from having to touch 100 files. For the first case, downstream can likely create their own For the second case it might be nicer, if there would be a "migration plan". For example with one version introducing new, parallel APIs without (or disabled by default) deprecation warnings, etc. Having this in properly planned means that "the customer" can decide on their own, which version steps they want to take. (If they jump on latest, they may not complain!) |
Beta Was this translation helpful? Give feedback.
-
|
Yes, exactly my point. |
Beta Was this translation helpful? Give feedback.
-
That is what I intended to cover with the bullet point about "larger deprecation campaigns" and the one I linked as an example is basically the only big one FairMQ ever did and it was announced way ahead (Mar 21 2022) of the actual
But how would upstream know how much warnings it will produce in the downstream compilation in general, even a single symbol deprecation may cause millions of warnings, does it not? |
Beta Was this translation helpful? Give feedback.
-
Well usually upstream has some ideas on how the code should be used (examples / tutorials!). If downstream deviates from that drastically, then they either should be in contact with upstream anyways or have no reason to complain. |
Beta Was this translation helpful? Give feedback.
-
|
About wall time between deprecation and removal: I don't think, the wall time is really important in this area. As upstream you can't usually influence when downstream switches to which version. If the ReleaseNotes are well written, then downstream can decide on their own on which version to jump and thus decide on their adoption rate of one particular change. What might actually be a point: Required changes per wall time. So if upstream would deprecate 100 APIs per week (and removes them six months later), then this means a lot of work for downstream. |
Beta Was this translation helpful? Give feedback.
-
I fully agree and I am happy to even implement something like this by e.g. limiting major releases (as the discussion here so far concluded, we basically want semver semantics, ergo API removal only happens in major releases) to a certain rate, let's say one per 3 months or one per 6 months. A slightly different variant would be the commitment of upstream to support every major release a minimum amount of time, so that downstream is always guaranteed to be able to stick with any major release for this amount of wall time. However, what we have not worked out yet, is the definition of a "required change". Nobody has made a convincing argument yet, why a deprecation warning by the compiler is perceived by downstream as a requirement to change. As @mattkretz has pointed out as well as @davidrohr did earlier downstream has already full control on deprecation warnings now (and I offer to make this control even more fine-grained by providing a FairMQ-specific switch on top). Only @ktf seems to not be happy about this for some reason. He even stated himself "Yes, I could temporarily turn off |
Beta Was this translation helpful? Give feedback.
-
edit: Now outdated, once the discussion threads conclude, I will propose a second revision. Read the following policy text as revision 1 or proposed text:
Ideally, one would want to get every public API correct from the start and never have to change anything forever. However, in reality, programmers make mistakes, requirements change over time, or the project simply evolves. To minimize avoidable friction, we would like to communicate the following API Deprecation and Removal Policy to both users and developers:
[[deprecated]]attribute if applicable#pragma GCC warning ...(or any other compiler warning mechanism that cannot be filtered by the user) must be announced in one additional release before the deprecating releaseThe above policy would allow for deprecation and removal of a public API in two consecutive releases. However, in such a case, the user may always opt-in to a 3-phase-deprecation-removal still by using
-Wno-deprecated-declarations, or-DFAIRMQ_NO_DEPRECATED_DECLARATIONSpassed to the compiler and/or CMakeBeta Was this translation helpful? Give feedback.
All reactions