hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: API/ABI compatibility; was RE: .HttpCacheEntry.getVariantURIs() is deprecated - can we delete it?
Date Tue, 11 Jan 2011 13:31:46 GMT
On 11 January 2011 12:36, Oleg Kalnichevski <olegk@apache.org> wrote:
> On Tue, 2011-01-11 at 11:23 +0000, Moore, Jonathan wrote:
>> Well, the tradeoff here is that it breaks binary compatibility with the previous
4.1 beta releases.
>>
>> I'm ok with removing it; we don't use it internally in the codebase anywhere anymore,
and I think it's unlikely someone built a new storage backend that relied on it or tried to
extend the cache module internals based on the beta release. I'd certainly like to avoid shipping
new GA code where some of the new stuff is deprecated out of the starting gate. :)
>>
>> However, I'd like to hear Oleg's opinion on this -- he has pretty strong feelings
about binary compatibility (certainly well-placed when talking about backwards compatibility
for GA releases).
>>
>> Jon
>
> Jon, Sebastian
>
> I personally think that the whole concept of binary compatibility for
> anything other than bugfix releases is simply flawed. I would love to be
> able to remove all deprecated code immediately. I would love to be able
> to upgrade HttpCore to Java 1.5 and make some other API changes here and
> there. The trouble is that binary compatibility is used by some as a
> criterion of a project's maturity and stability. For example, Google
> still ships a very outdated version of Httpclient with its Android
> platform supposedly because half a dozen variables were made final
> between the official API freeze and the 4.0 GA release.

I find that hard to believe.

It's more likely that they have not allocated resources to do the
necessary acceptance testing.

> Basically it is up to us to decide whether or not we want to adhere to
> strict interpretation of the API / ABI compatibility rules.

Yes.

Each project sets its own rules (hopefully similar to others) for what
version bumps are needed for specific types of changes.

The rules are important, as they set the user expectations for upgrades.

We should document the rules we use.

> For instance, Lucene simply does not guarantee API compatibility between
> minor release. Period. No one (as far as I know) had a heart attack
> because of that.

And Commons allows Java version incompatibility in minor releases -
(though I would hope they would use a major version bump for requiring
the latest version of Java shortly after its release!)

> Having said all that I do think we ought not break the API compatibility
> because of a lone deprecated method. As long as we do not have a very
> strong case for breaking the API we should continue to maintain it.

I think that depends on the particular case.

For example, a public method that is not intended for external use
(i.e. is only public because of internal code layout) should not be
considered as part of the API, even though it will appear in a Clirr
report.

There are also degrees of incompatibility, depending on how likely it
is that the method is used.

In this particular case, the method has never been part of a GA
release, which I think is borderline.

The release notes say:

===========================
Release 4.1 BETA1
-------------------
HttpClient 4.1 BETA1 finalizes the 4.1 API and brings a number of
major improvements to the HTTP
caching module.
...
Release 4.1 ALPHA2
-------------------
...
Compatibility notes
-------------------
(1) Please note the HTTP caching module is still considered experimental and
its API may change significantly in the future releases.
===========================

The RN don't say that the caching module is no longer considered experimental.
I think it's arguable that the caching API may still change.

> However, I can well imagine that we collectively decide that all code
> deprecated between 4.0-beta1 and 4.1 GA be removed in the 4.2 branch,
> run an open vote on it, and, if approved, stick to that decision.

If we are not agreed on removing the method now, we should run that
vote now, so we can update the Javadoc accordingly.

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

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


Mime
View raw message