I figured I’d take this discussion up with the experts and founding fathers. ;)
https://github.com/semver/semver/issues/508 -jake > On Apr 4, 2019, at 8:23 AM, Anthony Baker <aba...@pivotal.io> wrote: > > 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 >>>>>> >>>>> >>> >
