[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [handly-dev] Handly 0.4 : Focus on API quality

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