Can we bring the discussion back around? I feel like we have two
separate things going on here.
1) Can we avoid further churn in the public API for [1.7.0,2.0.0] by
avoiding any removal or additional deprecation.
2) In 2.0.0, what are we actually going to remove that is already deprecated
re #1, I don't think we have consensus, but I think that is a moderate
middle ground. Some wouldn't mind normal deprecation cycles for normal
releases between now and 2.0.0; others have argued that we should not
alter the public API at all before 2.0.0. I think we should try to focus
the conversation here and come up with a compromise.
re #2, I think we can re-visit what (if anything) is candidate for
deletion when 2.0.0 happens. I don't think that directly necessary to
answer to come to a conclusion on #1.
Correct me if I have misspoken.
Christopher wrote:
Sorry, another way to put this (more succinctly) is that I have removed
*all* deprecated APIs prior to 1.7 with the exception of the
instance.dfs.{uri,dir} configuration properties in my local 2.0 branch.
After some hindsight, essentially what I was trying to propose is that we
treat 1.7 as a "minor" release, and any subsequent 1.x releases as normal
"minor" or "patch" releases, according to definitions of those for Semver.
For the record, Semver also doesn't address what *should be* removed, only
what *can be*. If anybody wants to keep something around longer, I don't
consider that blocking these minimal guidelines. If we end up adopting
Semver, and apply the constraints to 1.7 moving forward, these proposed
guidelines are moot.
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
On Wed, Dec 3, 2014 at 12:38 PM, Christopher<[email protected]> wrote:
On Wed, Dec 3, 2014 at 10:10 AM, Keith Turner<[email protected]> wrote:
On Tue, Dec 2, 2014 at 3:01 PM, Christopher<[email protected]> wrote:
Following the conversation on the [VOTE] thread for ACCUMULO-3176, it
seems
we require an explicit API guidelines at least for 1.7.0 and later until
2.0.0.
I hereby propose we adopt the following guidelines for future releases
(if
we produce any such releases) until 2.0.0:
API additions are permitted in "major" 1.x releases (1.7, 1.8, 1.9,
1.10,
etc.).
API should be forwards and backwards compatible within a 1.x release (no
new additions to the API in a "bugfix" release; e.g. 1.7.1).
New API in 1.7.0 and later 1.x releases will not be removed in 2.0
(though
they may be deprecated in 2.0 and subject to removal in 3.0).
Existing API in 1.7.0 will be preserved through 2.0, and should only be
subject to removal if it was already deprecated prior to 1.7.0 (though
they
may be deprecated in 2.0 and subject to removal in 3.0).
This stmt can lead to disagreement later over what deprecated methods are
removed in 2.0. We could explicitly list which deprecated methods will be
removed as part of this vote. Alternatively, we could add a clause saying
there will be a vote prior to 2.0 over which methods are removed. If we
decide now, then we could add something to 1.7.0 javadoc stating the
method
will go away in 2.0.
These are intended to be minimal guidelines, not a comprehensive list of
what should be removed... only guidelines to ensure we don't remove
something in a breaking way. I'm fine with disagreeing with what can be
removed later... so long as we're agreed on certain minimal things which
cannot be removed, to ensure a smooth transition.
However, for the record, the comprehensive list of things I expect to
remove in 2.0, all of which were deprecated in 1.6.0 or prior:
Constants.NO_AUTHS (deprecated since 1.6.0)
ScannerOptions.{set,get}TimeOut(...) (deprecated since 1.5.0)
Connector.create[MultiTable]Batch{Deleter,Scanner}(...) without
BatchWriterConfig (deprecated since 1.5.0)
Instance.getConnector(...) that doesn't take an AuthorizationToken
(deprecated since 1.5.0)
MutationsRejectedException constructor (deprecated since 1.6.0)
MutationsRejectedException.getAuthorizationFailures() (deprecated since
1.5.0)
some ZooKeeperInstance constructors replaced with ClientConfiguration
(deprecated since 1.6.0)
some SecurityOperations methods (deprecated since 1.5.0)
TableOperations.getSplits() (deprecated since 1.5.0)
non-range TableOperations.flush() (deprecated since 1.4)
Constraint.getAuthorizations() (deprecated since 1.5.0)
static KeyExtent.getkeyExtentsForRange() (deprecated and unused utility
method)
Value constructor with copy param (deprecated and unused)
Aggregators (deprecated since 1.4)
protected Accumulo{Input,Output}Format.getToken[Class]() (deprecated since
1.6.0)
protected AccumuloInputFormat.getTabletLocator() (deprecated since 1.6.0)
protected AccumuloInputFormat.setupIterators() (deprecated since 1.5.0)
RangeInputSplit (deprecated since 1.5.2)
Additionally, I was going to remove the non-public API trace module
deprecated since 1.7 as part of the switch to HTrace.
I've actually already done this on my local 2.0 branch I'm working in, but
I have no intentions to remove anything else... and these guidelines would
effectively prevent me from doing so.
I would be opposed to adding javadocs stating methods will go away in 2.0,
unless they are already deprecated. The fact is... 2.0 is not available,
and we don't know exactly what will go away. But, we can establish
guidelines to give us an idea of what will not go away. That's the purpose
of the above guidelines.
I have been playing around w/ the following command to see whats currently
deprecated in master.
find core/src/main/java/org/apache/accumulo/core/client/ -name "*.java" |
grep -i -v impl | xargs grep Deprecated -C 3
The purpose of these guidelines are to ensure the ability to add
additional
functionality and evolve API naturally, while minimizing API
disruptions to
the user base, in the interim before 2.0.0 when we can formally adopt an
API/versioning policy.
Exceptions to these guidelines should be subject to a majority vote, on
a
case-by-case basis.
Because these relate to release planning, this vote will be subject to
majority vote, in accordance with our bylaws pertaining to release
planning
and voting, and will be open for 3 days, concluding at 2000 on 5 Dec
2014
UTC.
--
Christopher L Tubbs II
http://gravatar.com/ctubbsii
