Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipse-pmc] Adoption of newer Eclipse versions, and API Deprecation Policy

PS I think we should also talk about potential benefits of investing along these ways:
  • Easing our company's Eclipse adoption frees resources for Eclipse development
  • Making API and non-API usage more explicit allows us to deprecate functionality and thus get more freedom for change
  • Getting API usage and deprecation processes in place links us more closely to the consumers and helps better discussions about anticipated changes
I strongly believe that freeing ourselves from at least some legacy burden is extremely important for Eclipse, and a formal API usage / API deprecation process is one step in this direction (we need to know what the community really needs such that we can react properly).
Martin Oberhuber, Senior Member of Technical Staff, Wind River
Target Management Project Lead, DSDP PMC Member

From: eclipse-pmc-bounces@xxxxxxxxxxx [mailto:eclipse-pmc-bounces@xxxxxxxxxxx] On Behalf Of Oberhuber, Martin
Sent: Thursday, January 08, 2009 5:07 PM
To: eclipse-pmc@xxxxxxxxxxx
Subject: RE: [eclipse-pmc] Adoption of newer Eclipse versions,and API Deprecation Policy

Hi all,
after chatting with Philippe on the phone, here is an alternative wording:
In the Eclipse Project, we see that many clients have big problems migrating their products to the yearly new Eclipse version:
  1. API Compatibility: In spite of striving hard to remain binary compatible, there are always cases where wrong API needs to be rectified. This leads to effort on the client side. How can inevitable migration effort be eased?
  2. Bundle Internals: Clients use internal non-API for a variety of reasons (e.g. "monkey see, monkey do" programming; not understanding the clean API; functionality not available as API, or introduced only after functionality was initially written). Becoming API clean would be the obvious solution, but in many cases this is not possible in the time frame available. How can we help clients become API-clean, and how can we help protect investment where API cleanliness is impossible?
  3. Feature additions: Even if clients are API clean, introduction of new features can make the clients look "old-fashioned" or non-conforming in the latest incarnation of the Platform. Take Colors in SWT trees for instance: before this feature, textual markup had to be used for decorations, now colors are used. How can we help clients detect usage of obsoleted features, and migrate to the new feature more easily?
These are only some examples where we see that in spite of remaining binary compatible, clients cannot always migrate to newer Eclipse versions easily. Do others see similar issues, or is this a pain that only IBM products see? Are there other pain points to add to the list above? What can or should be done to ease the situation? Here are some initial ideas:
  • For (1) API Compatibility: Create new Javadoc tag(s) and associated tooling, such that clients can see when they use functionality that has somehow changed. For instance: "@changed 3.4 passing null argument now leads to no-op instead of performing default operation". API Tooling converts usage of @changed API into task markers that clients can work on.
  • For (2a) Internals: Allow clients to run a report on their (closed-source) code, such that all usage of non-API is properly reported and documented. This report could be the discussion base such that we can understand what non-API is "important" and/or help them find the correct API-clean counterpart for non-API use. Ideally, such a "redirection" of non-API to API could be captured in a way that is automated, i.e. the next client who sends in a report about using a particular non-API is automatically pointed to the correct API-clean way of doing something.
  • For (2b) Internals: Also, create a programme for contributed regression tests: Allow clients to send in regression tests that mimic their specific usage of non-API. Have the test run at Eclipse, but have the client be resonsible for the test. Thanks to the test, changes in non-API are detected much earlier and can be acted on properly.
  • For (3) Feature additions: Create a "soft deprecation" javadoc tag, which tells clients that their use of functionality is still available (and won't go away too soon), but also point them at how to use the newer, superseding functionality (This is actually a variant of 2a).
As a corollary of (3), we should also talk about formal API (and non-API) deprecation policies, i.e. for how long we as a Community think that deprecated functionality needs to be kept around, and how the Community should be informed about deprecation. The goals of this discussion should be to
  1. Produce a clear set of rules for Plugin Providers that, if followed, helps adopters of new versions (e.g. how to document and tag changes).
  2. Produce a process and tooling for Plugin Consumers that helps them (a) become more API clean, (b) improve discussions about non-API, and (c) protect their investment in non-API if necessary.
So well that's quite a bit more than the 2 or 3 sentences that I asked for, but that's how I tried to capture what I understood from what Philippe said.
Comments and thoughts welcome...
Martin Oberhuber, Senior Member of Technical Staff, Wind River
Target Management Project Lead, DSDP PMC Member

From: eclipse-pmc-bounces@xxxxxxxxxxx [mailto:eclipse-pmc-bounces@xxxxxxxxxxx] On Behalf Of Philippe P Mulet
Sent: Thursday, January 08, 2009 11:34 AM
To: eclipse-pmc@xxxxxxxxxxx
Subject: Re: [eclipse-pmc] API Deprecation Policy

Sure. How about ?

The cost for migrating an Eclipse-based product to the next release is often far from negligeable and for a range of reasons (including API compatibility, use of other bundle internals, becoming obsoleted by feature additions, ...). We should construct the list of pain points, and start thinking on how these could be eased, baring in mind that ultimately, moving to a service release should be a no brainer.

From: "Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>
To: "Mike Wilson" <Mike_Wilson@xxxxxxxxxx>, Philippe P Mulet/France/IBM@IBMFR
Cc: eclipse-pmc@xxxxxxxxxxx
Date: 01/07/2009 10:13 PM
Subject: [eclipse-pmc] API Deprecation Policy
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx

Hi Mike, Philippe et al,
regarding the API Deprecation discussion at the AC: I'm planning to send out a short reminder E-Mail to the AC some time tomorrow. As part of that E-Mail, I could simply mention that the Deprecation discussion is scheduled for the meeting. If you guys could come up with a few brain teasers for that discussion (just 2 or 3 sentences), that might help sparking off a nice discussion. What do you think?
Martin Oberhuber, Senior Member of Technical Staff, Wind River
Target Management Project Lead, DSDP PMC Member
eclipse-pmc mailing list

Sauf indication contraire ci-dessus:/ Unless stated otherwise above:
Compagnie IBM France
Siège Social : Tour Descartes, 2, avenue Gambetta, La Défense 5, 92400 Courbevoie
RCS Nanterre 552 118 465
Forme Sociale : S.A.S.
Capital Social : 609.751.783,30 €
SIREN/SIRET : 552 118 465 02430

Back to the top