Tldr: Here's what I propose: 1) contributors should add dates and/or POI versions to @deprecated annotations for new commits 2) contributors should add @since version annotations to new features 3) new features may be removed without deprecation only if added prior to a final build and removed before or during the next final build (same release series)
I really appreciate the folks who leave a date and/or POI version in the Javadoc when deprecating the feature, as it makes removal much quicker [1]. I've been trying to remember to do so as well for my commits. I think it'd also be good to add what version a feature was new in, so that users with projects using an old version of POI, looking to use a feature that isn't in their version of POI, know the bare minimum version they'd need to upgrade to in order to get the feature. This may encourage people to upgrade when they see how much cool stuff is in the newer versions. Can we automatically check for `@deprecated <release version or date>` or `@since <release version>` in Jenkins? > After two releases the deprecated stuff can be removed. > Does "release" mean a final or a beta release? I'd say release means final release, and excludes beta. Companies that use POI may choose not to run "beta" libraries in production applications, so developers may ignore our beta releases until final comes out. If our 2-release rule included betas, this wouldn't give users a chance to see an API go from supported to deprecated to removed in final-only upgrades. It might be fair to say any feature that will be removed must be marked as deprecated in at least 1 final release so that anyone can upgrade their project one POI version at a time, and can check and fix deprecated features. Holding onto deprecated features for at least 2 versions allows users to catch up to the latest version by sequentially upgrading POI, skipping every other version. If users assume that any changes made in a beta build may change before final release, then we have the flexibility to remove without first deprecating any feature that was added in a beta version in the same release series. As soon as a final is released, a feature should be deprecated for one final release before removing. [1] Side-note: viewvc's annotate/blame feature doesn't work for most files On Nov 24, 2015 4:44 PM, "Andreas Beeker" <[email protected]> wrote: > Hi, > > this is partly a follow up to [1] and [2] - and sorry in advance to bring > this up again, > but I feel we are too conservative. > > Summary: > When we introduce new methods/enums/classes/... we try to be compile > compatible with older versions. > After two releases the deprecated stuff can be removed. > Logic can be annotated internal, making it easier to change. > > Does "release" mean a final or a beta release? > If it's a beta, it would probably make more sense to remove the deprecated > stuff in the final release > and not spanning it over to the next final round. But then one could also > drop the deprecated stuff > immediately, because it's just a beta ... > > I'm not sure if the following conclusions based on the download stats [3] > (only PMCs) are valid: > There's not much interest in betas after the final is out (... I know > captain obvious is greeting) > 3.9 is still quite frequently requested - the later version are approx. > equally downloaded. > - are people are so slowly adapting, because the older version satisfy > their needs? > - if we have the 2-release-deprecate-rule, does this really matter, i.e. > are people gradually > upgrading the version or do they jump over several releases anyway and > need to be > prepared for api breaks? > > So lets assume we add a version comment to each deprecated element for a > later removal. > In this case we have to check the logic twice, when deprecating it and > when removing it. > I think this is tedious ... and the removing won't be done later ... > having lots of deprecated stuff > around (see HWPF), which nobody wants to touch. > > For X/HSLF I've decided to remove stuff immediately - having the > scratchpad label as an excuse. > > I try to think about a measure, when something should be kept available > for longer or > can be removed immediately ... how about how often it used in the examples? > i.e. if less than 2 matches are found -> removed it > otherwise deprecate it > > Best wishes, > Andi > > [1] > http://apache-poi.1045710.n5.nabble.com/Logging-Binary-compatibility-tt5719152.html > [2] https://bz.apache.org/bugzilla/show_bug.cgi?id=58636 > [3] https://repository.apache.org/#central-stat > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
