Let’s separate the discussion into these parts: - What does SemVer say and how do we apply it - When should we remove deprecated code - Should we remove the admin source code entirely
1) SemVer Straight from the spec: > Major version X (X.y.z | X > 0) MUST be incremented if any backwards > incompatible changes are introduced to the public API @Jens - doesn’t “new major version” imply n.0.0? Downstream consumers of SemVer-compliant software expect that “backwards compatibility” means they can upgrade to a new minor or patch release and things will continue to just work—no changes required. If you think about how we upgrade our library dependencies we have that same expectation. When I upgrade from log4j 2.11.1 to log4j 2.11.2 I don’t expect to have to modify any source code. IMO, the clarity that SemVer brings to the question of “Can I upgrade safely?” Is its main benefit. If we blur the lines and break stuff without signaling via major versions, then our users will be less inclined to trust us and will upgrade less frequently IMO. 3) Deprecation Unlike users, SemVer places no value judgement on version numbers and assumes that major version numbers are “free” (aka infinite). Some projects have major versions like 42.0.0 (wow!). Unfortunately most users *do* expect certain things like new features from major versions. And if the cost of the upgrade is higher than the value gained from the upgrade then there’s a strong disincentive to move forward. We’ve all seen OSS communities that have fragmented due to the cost of changing to a new major version (e.g. python). I’d sure like to avoid that. Clearly we have a lot of long-deprecated API’s that we want to clean up. That’s important to *us*. I also want to understand why our *users* will want to upgrade to a geode-2.0.0 release. Let’s spin off a separate thread to discuss what that looks like and how we handle the transition using branches, prereleases, or other mechanisms to manage breaking changes. 2) Admin source code This is a grey area for me. While technically it is part of the API, it’s also true that it’s been broken / unusable (not to mention obsolete) for the entire time it’s been part of the geode project. +1 to remove. Anthony > On Apr 4, 2019, at 6:36 AM, Jens Deppe <jensde...@apache.org> wrote: > > I'm not sure if I'm interpreting various parts of this conversation > correctly, but it seems that one view being assumed is that the actual > removal of deprecated APIs *must* happen in the first version of a major > release bump. i.e. for this discussion that would be *2.0.0*. I don't > believe this is a correct interpretation of the following; taken from > https://semver.org/ > > Before you completely remove the functionality *in a new major release* >> there should be at least one minor release that contains the deprecation so >> that users can smoothly transition to the new API. > > > There is no mention of it needing to happen in the *n.0.0* version; just > *sometime* within a new major version. > > Given that, these APIs were definitely deprecated before 1.0 and I believe > we're within the definition of *semver* to be free to remove them now. > > +1 to removing them any time before 2.0.0. > > --Jens > > On Wed, Apr 3, 2019 at 7:38 PM Jacob Barrett <jbarr...@pivotal.io> wrote: > >> That’s your interpretation of semver. I interpret The API not to be broken >> within a major as those that are still valid when the major is released >> despite the availability of deprecated symbols from previous major. Just >> because I can access symbols does not make it API. API is the combination >> of documentation, annotation and availability of the symbols. If the >> symbols are available but marked deprecated and not documented anymore then >> it is. It API. >> >> Yes under your interpretation it would require that availability be >> removed at the major release too so that a consumer that ignore deprecation >> warnings when compiling with the new version got a compilation or runtime >> error later up updating a minor. >> >> I think that error is well deserved. We do a disservice to our customers >> by allowing them to continue to limp along on deprecated, unmaintained and >> untested APIs because we missed an arbitrary window to remove the symbols. >> >> If however the community agrees with you interpretation then we must make >> sure a ticket is created for the next major with a list of deprecated items >> and updated when new items are deprecated so that the task is performed at >> the major release. A chore needs to be undertaken to remove all deprecated >> APIs at the start of each major development cycle. The short of it is we >> can’t miss this arbitrarily limiting window. >> >> -Jake >> >> >>> On Apr 3, 2019, at 3:58 PM, Alexander Murmann <amurm...@apache.org> >> wrote: >>> >>> Would we announce that we aren't following semver anymore because bumping >>> the major version is somehow too expensive? >>> >>>> On Wed, Apr 3, 2019 at 3:29 PM Kirk Lund <kl...@apache.org> wrote: >>>> >>>> 1) +1 YES. If we continue to *not* have at least one major release per >>>> year, then I 100% support the removal of deprecated APIs and features >> in a >>>> minor release such as 1.10. If we decide to have at least one major >> release >>>> per year, then I'd be willing to revisit this and consider not allowing >>>> removal in a minor release. I do *not* support perpetually deferring >> major >>>> releases to avoid facing the removal of deprecated APIs -- that's just >>>> ridiculous as it keeps our maintenance costs much higher than they need >> to >>>> be. >>>> >>>> 2) +1 to remove anything in 1.10, or any other minor release, that was >>>> already deprecated in Geode 1.0 >>>> >>>>> On Tue, Apr 2, 2019 at 5:05 PM Dan Smith <dsm...@pivotal.io> wrote: >>>>> >>>>> Hi devs, >>>>> >>>>> The org.apache.geode.admin package has been deprecated for about 7 >> years >>>>> [1]. >>>>> >>>>> I'd like to remove it, or at least move it to a separate module. I >>>> actually >>>>> started some work to move it to a separate module [2]. However in the >>>>> course of this process, I've found that this module has extremely >> little >>>>> test coverage, so I'm not confident in the move. For example, it has a >>>>> whole JMX manager feature (different than our current JMX manager) >> which >>>>> does not appear to have any tests. This JMX manager feature won't work >> as >>>>> shipped unless you find and add some mx4j jars to your classpath. >>>>> >>>>> I think the best course of action is probably to remove it entirely. >>>>> However, this does bring up a couple of questions: >>>>> >>>>> 1) Is it ok in general to remove deprecated API in a non X.0 release >> (eg >>>>> geode 1.10 instead of geode 2.0)? >>>>> >>>>> 2) How about in this case, when this feature has been deprecated for so >>>>> long, and may or may not work? >>>>> >>>>> -Dan >>>>> >>>>> [1] >>>>> >>>>> >>>> >> https://geode.apache.org/releases/latest/javadoc/org/apache/geode/admin/package-summary.html >>>>> [2] Draft PR for moving the org.apache.geode.admin to a separate >> module - >>>>> https://github.com/apache/geode/pull/3392 >>>>> >>>> >>
