Community
Participate
Working Groups
The extension point org.eclipse.help.base.luceneSearchParticipants exposes classes from Lucene and this has created a binary incompatibility if we were to switch to Lucene 1.x to 2.x. In Eclipse 3.6 a new extension point "searchParticipant" was created as a replacement. While Lucene 2.x is binary incompatible Lucene 3.x removes some classes which were deprecated in 2.x and could completely break any clients of the old interface. We should start the process of eliminating luceneSearchParticipants by flagging it for deletion in a future release. See Bug 298510 - [Help][Search] org.eclipse.help.base API uses classes from Lucene for more background.
Created attachment 167348 [details] Patch in org.eclipse.help.base to add comments announcing future removal
John - a couple of questions. I was looking at http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy#Announcing_API_Removal - does the announcement of future removal (as opposed to the actual removal) require full PMC approval? Also which page of the porting guide should the announcement go in, incompatibilities.html or recommended.html?
(In reply to comment #2) > - does the announcement of future removal (as opposed to the actual removal) > require full PMC approval? Yes, the idea here is to let the PMC discuss it and decide if it makes sense, before broadcasting to the wider community and avoid unnecessary churn. > Also which page of the porting guide should the > announcement go in, incompatibilities.html or recommended.html? There is a new "removals.html" page that it should go in. This removal sounds quite reasonable to me - if you send out the request I can argue in favour of this one at the next PMC call.
This is the summary of the changes to be made, the impact and the rationale. The following extension point will be removed: org.eclipse.help.base.luceneSearchParticipants The following API classes will be removed: org.eclipse.help.search.LuceneSearchParticipant org.eclipse.help.search.ISearchIndex org.eclipse.help.search.XMLSearchParticipant Rationale for change. The class LuceneSearchParticipant exposes classes from Lucene in it's method parameters, specifically org.apache.lucene.document.Document and org.apache.lucene.document.Field. Between Lucene 1.x and 2.x there is a binary incompatibility in these Lucene classes which is inherited by LuceneSearchParticipant, this has prevented the help system from upgrading to Lucene 2.x. With Lucene 3.x the situation gets worse because some of the methods in Document and Field which existed in 1.x were deprecated in 2.x and removed in 3.x, clients of this extension point could easily run into this problem. Impact on downstream clients. Any users of this extension point will be required to use the replacement extension point org.eclipse.help.base.searchParticipant instead. We do not believe that this extension point is widely used.
I have two questions here. 1.) The replacement extension point org.eclipse.help.base.searchParticipant is currently documented as "since 3.5", but in the Galileo Docs I do not find it: http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/reference/extension-points/index.html could it be that it was added in 3.6 only? - Also, as per 3.6M7, the "example" in the docs of the new extension point still references the old one (luceneSearchParticipant)!! 2.) Do we know for sure that the new extension point covers all cases that the old one could cover? How "expensive" is migration for clients? I would like to see some documentation in a migration guide that explains what's involved in migrating from the old extension point to the new one, before I can give my +1 for announcing removal. Announcing removal of API is a serious issue. With announcing removal, we need to expect that clients will want to migrate. We should make sure that we have paved the way for migration as much as we can.
Also, in the patch I'm missing usage of the official "deprecated" element in the .exsd for the extension point. Using this element is important in order to allow (future) tooling detect usage of deprecated extension points and report them as warning or error. That's an important aid for clients to migrate. <annotation> <appInfo> <meta.element deprecated="true" replacement="foo.bar" /> </appInfo> </annotation>
(In reply to comment #6) > Also, in the patch I'm missing usage of the official "deprecated" element in Please disregard this comment - I found that the deprecated element does exist in the .exsd as expected already, so there was no need adding it to the patch.
In response to the questions in Comment 5. The extension point "searchParticipant" was added in Eclipse 3.6. Do we know for sure that the new extension point covers all cases that the old one could cover? - Because the old API exposed Lucene classes a client could do things in the old API that are not possible in the new API but the new API can do the one thing which is the essence of the extension point which is to add documents of any type to the search index Migration to the new extension point was pretty simple for the two bundles in Eclipse which use the luceneSearchParticipants extension point. Allowing the user to have access to the Lucene API also exposes the client to changes in that API, I experimented with using Lucene 3.0 with Eclipse 3.5 after changing the required bundle version for Lucene and found that I had compilation errors in org.eclipse.ui.cheatsheets which uses methods which were deprecated in Lucene 2.x and removed in Lucene 3.x. There is definitely a trade off here - I am proposing announcing the removal of an extension point which we know will cause problems for users in the future if the SKK is upgraded to Lucene 3.x, which is something we eventually will want to do. On the other hand removal of the extension point in itself will cause work for the clients. The deprecation of luceneSearchParticipants should encourage clients to migrate away from the use of this extension point but for those clients who choose not to migrate the question is whether it is preferable to leave the extension point in place even though it may force them to recode whenever Eclipse switches to a newer full version of Lucene or remove the extension point altogether and force clients to do a single migration to the new extension point. I think removal is in the long term going to be less painful for users than to try to keep this deprecated extension point alive but I could be persuaded to wait till next year to announce the removal.
Thanks Chris. I think that announcing removal is OK, and the sooner we do it the better (because it increases chances that clients actually respond back and potential open issues are uncovered). Announcing removal doesn't mean that we actually must remove it -- it just opens the door for doing so. I would still suggest that along with announcing removal, we also provide a "good toolset" for clients to understand the implications of moving. In this case, I think this should include 1.) fixing the current ISV docs for the new extension point (example, @since tag) 2.) adding a sample to the migration guide that shows how and where the Eclipse SDK did migrate from the old extension point to the new one 3.) adding a feedback channel for clients to the migration guide that enables them to ask questions, provide input or veto the removal. I believe the channel would just be this bug.
I agree that announcing the removal leaves open the possibility that we do not remove the API at the first opportunity if the feedback from the community is negative. I also agree with the suggestions for the migration toolkit.
We discussed this at last week's PMC call and agreed to announcing the deletion. As with any deprecation, there should be a migration guide entry in the "Adopting 3.6 mechanisms" section of the migration guide as described by Martin.
Chris, Curtis, please review the JavaDoc changes. I will be writing instructions on how to port from the old extension point but as doc changes those do not need approval for RC2.
Is it possible to be more specific about when it will be removed? I usually see notices like "This will be removed in [version]". I'm guessing you phrased it the way you did because you don't know the future version number "n releases after 3.6?"
The plan is to remove the extension point in the June 2012 release (3.8/4.2). If the community gives us feedback that this is too early the removal would be delayed.
This looks good to me, though I admit I have not reviewed a deprecation before (so I don't know much about the process). I did notice that the <documentation> tag of /org.eclipse.help.base/schema/luceneSearchParticipants.exsd does not have the year updated to 2010 - so that may need to be updated.
You are right, I should update the copyright to 2010. If I make that change can you approve the bug? I don't think there is a need to add a new patch with the new copyright date.
Yes, of course. I approve.
Patch committed to HEAD, Fixed
Created attachment 169246 [details] Detailed instructions for porting to the new extension point.
