deprecations under semantic versioning

["pj.fanning" <fa...@yahoo.com>]

I haven't thought too much about the version number to put in @Removal
annotations since we moved to semver for 4.0.0. I've just been routinely
adding @Removal version 4.2 based on the old deprecation strategy in POI
3.x.
I'm wondering whether we should say that 4.1 is the removal version for
anything deprecated in 4.0.x.
Or should the removal version be 5.0?

I guess the real question is about how we are going to schedule releases
generally.
As an example, Apache Spark does a new minor release every 6 months or so
(eg an upgrade from 2.2.x to 2.3.0). If we follow a similar strategy, then
we could choose to keep the equivalent 2 minor releases retention so that
deprecated methods are removed in a reasonably timely way without causing
too much disruption by removing them too quickly.



--
Sent from: http://apache-poi.1045710.n5.nabble.com/POI-Dev-f2312866.html

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org

RE: deprecations under semantic versioning

["Murphy, Mark" <mu...@metalexmfg.com>]

I think with semantic versioning, we can't do anything that breaks compatibility except on major version changes, so no removals until 5.0. We can add features on minor version changes, and point changes are just for bug fixes. I think it would be good to schedule minor and major versions, and add point releases as needed for bug fixes in between. I would be good with 6 month minor releases, and annual major releases. I am not particularly keen on sticking with the two release maximum to removal. Removing deprecated items makes for a lot of churn if it is done too rapidly, and that will reduce the usefulness of POI to businesses. Which in turn encourages those businesses to remain on older releases. Where I am working, we are stuck at 3.14 for just that reason. We may make the jump to 4.0 at some point, but it will be a gradual migration rather than an over night refactoring simply because there is too much other work to go about fixing something that is not broken.

My suggestion is that deprecated methods be removed at the next major release as long as there has been at least one intervening minor release. So, for example, if we settle on 6 months for minor releases, and annual major releases, then anything deprecated at 4.0 would be removed at 5.0, but anything deprecated at 4.1 would not be removed until 6.0. Another thing to consider is that forcing refactoring on an annual basis will be a reason to avoid upgrading, so we should designate long term support releases that do not break compatibility. I like the Ubuntu model for this. That way folks who need to be on the bleeding edge can have that, but those who need less churn can still have bug fixes, and maybe some added features. Is maintaining multiple branches as easy in SVN as it is in Git? If not maybe this would be a reason to shift to Git as the primary repository.

-----Original Message-----
From: pj.fanning [mailto:fanningpj@yahoo.com] 
Sent: Sunday, January 14, 2018 10:35 AM
To: dev@poi.apache.org
Subject: deprecations under semantic versioning

I haven't thought too much about the version number to put in @Removal annotations since we moved to semver for 4.0.0. I've just been routinely adding @Removal version 4.2 based on the old deprecation strategy in POI 3.x.
I'm wondering whether we should say that 4.1 is the removal version for anything deprecated in 4.0.x.
Or should the removal version be 5.0?

I guess the real question is about how we are going to schedule releases generally.
As an example, Apache Spark does a new minor release every 6 months or so (eg an upgrade from 2.2.x to 2.3.0). If we follow a similar strategy, then we could choose to keep the equivalent 2 minor releases retention so that deprecated methods are removed in a reasonably timely way without causing too much disruption by removing them too quickly.



--
Sent from: http://apache-poi.1045710.n5.nabble.com/POI-Dev-f2312866.html

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org For additional commands, e-mail: dev-help@poi.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org