Re: [handly-dev] Handly 0.4 : Focus on API quality

[Vladimir Piskarev <pisv@xxxxx>]

Greetings handly-dev,

 

I'm pleased to announce the availability of the 0.4 M4 milestone build, an attempt at API freeze towards the 0.4 release on Dec 11 2015.

 

P2 Repository: http://download.eclipse.org/handly/releases/0.4M4/repository

Archived Repository: http://www.eclipse.org/downloads/download.php?file=/handly/drops/0.4M4/handly-repository-incubation-0.4M4.zip

 

The 0.4 version, with its main goal of improving core Handly APIs, will necessarily be much more disruptive than previous releases. With this milestone build, we are seeking to provide current adopters with an opportunity to give it a try and leave feedback/raise concerns before it would be too late.

 

Here's a N&N list.

 

BREAKING CHANGES

DelegatingWorkingCopyBuffer's constructor IMPORTANT CONTRACT CHANGE
PLEASE MIGRATE YOUR CODE and release the delegate buffer properly
(probably only tests will be affected)
 see bug 476444 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=476444

 

Several API methods take IProgressMonitor now
* Handle#buildStructure
* SourceFile#buildStructure
* SourceFile#createStructuralAst
* SourceFile.ReconcilingOperation#reconcile

 

IBodyCache#putAll - new method
 see bug 477157 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=477157

 

IHandleDelta#getFlags() : int -> long

 

HandleDelta - multiple breaking changes
* public API remained largely the same
* protected API surface area was significantly reduced
 (i.e. many previously protected members are now private)
 see bug 480945 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=480945

 

ISourceElement#getElementAt may throw CoreException now
 -> use SourceElements#getElementAt if you need original semantics

 

ISourceFile#getFile may return null now
 see bug 480766 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=480766

 

DEPRECATED API

 

IElementForEditorInputFactory -> IInputElementProvider
 superseded by IInputElementProvider for all intents and purposes
 please bind IInputElementProvider instead of IEFEIF in your Xtext modules

 

ISourceFile#openBuffer -> getBuffer

 

IDocumentBuffer -> IBuffer#getDocument()

 

IBuffer#dispose() -> release()

 

NEW API

 

IHandle#toString(ToStringStyle)
 see bug 475446 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=475446

 

Working copy

* SourceFile#reconcile(boolean, Object, IProgressMonitor)
 see bug 473417 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=473417

* WorkingCopyInfo
* IWorkingCopyInfoFactory
* SourceFile#becomeWorkingCopy(IWorkingCopyBuffer, IWorkingCopyInfoFactory, ...)
 see bug 475862 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=475862

 

Buffers

* IBuffer#addRef/release (multiple independent ownership of the buffer)
 see bug 476444 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=476444

* SimpleBuffer
* ChildBuffer (initially called PrivateBuffer)
 see bug 476031 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=476031

 

Model adaptation (o.e.handly.model.adapter)
 see bug 472841 for details: https://bugs.eclipse.org/bugs/show_bug.cgi?id=472841

 

OTHER CHANGES

 

StructureHelper can now be used as it stands, i.e. without subclassing

 

Xtext 2.9 is supported now (along with 2.8)

 

 

For reference,

FULL LIST OF API RELATED ISSUES

https://bugs.eclipse.org/bugs/buglist.cgi?&classification=Technology&query_format=advanced&product=Handly&target_milestone=0.4&keywords=api&keywords_type=allwords

 

FULL LIST OF ISSUES WITH BREAKING CHANGES

https://bugs.eclipse.org/bugs/buglist.cgi?resolution=FIXED&classification=Technology&query_format=advanced&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&product=Handly&target_milestone=0.4&status_whiteboard=breakingchange&status_whiteboard_type=allwordssubstr

 

Best regards,

Vladimir

 

 

Greetings handly-dev,

 

API quality is going to be a very important theme for the 0.4 release. The goal is to attempt to finalize the *core* Handly APIs within the 0.5 time frame (Eclipse Neon). To accomplish that, we should try to get the necessary API changes into the 0.4 release, in order to allow sufficient time for community feedback (and further changes, if necessary).

 

Here is a tentative (most probably incomplete) list of enhacement requests related to API quality:

 

https://bugs.eclipse.org/bugs/buglist.cgi?&classification=Technology&query_format=advanced&product=Handly&target_milestone=0.4&keywords=api&keywords_type=allwords

 

Necessarily, this work will result in some breaking changes (hopefully for better than for worse). Therefore, I wanted to inform everyone about the scope of ensuing changes sooner rather than later. Please feel free to comment on these bugs or add yourself to CC list to stay up-to-date with ongoing development. It is also a good opportunity to raise concerns if there is something you strongly disagree with, or submit additional requests regarding API. I will try to keep you informed via this list as we're approaching the goal of better API quality.

 

Thanks and best regards,

Vladimir