blob: 95700a0033d839fb99dacf8ebdc00a5d3d1695d5 [file] [log] [blame]
Attendees: David, Kevin, Naci, Ted, Chuck
Special Guests: Tim DeBoer, Craig Salter
Two Problem areas discussed and resolved.
88013 [arch] Should tabbed property sheet be API
88016 [arch] Should web browser (view) be in base?
One resulted in WTP request for Eclipse 3.2
89087 WTP Request for Tabbed Properties Page in base UI component
We (further) discussed our group's mandate.
Generally agreed on following
We need to (continue to) make clear we do not "own" or define API or ensure its quality
(component leads, with their clients do that -- and there are no shortcuts for that hard work).
But, we do help ensure architectural integrity across components and projects and that the right level of right API exposed.
Also we can facilitate discussion across components and community and offer consultation when requested.
In the future, will review proposed API breakages, to help assess their cost/benefit trade-off.
I'll be submitting more detailed proposal on "facilitating communication" by holding "component open house"
sessions during M5 time-frame for any interested parties.
Following is a list of things we thought of that we can do to "ensure architectural integrity across
components and that the right level of right API exposed". While some members of the architecture group
may occasionally look specifically at code/designs with these following issues in mind, many of them are
"low level" items that will never been seen except by component teams and their clients. Feel free to
consult with Architecture team if questions or our review is requested for any concrete case.
1. An API is not just Types and Members ... its a statement of providing some functionality for clients.
So, obviously, the intended functionality must be clearly stated before the proposed functionality can be
assessed. We recommend the intended functionality be clearly documented in component overview documents
by M4.
2. What specific problem does the API solve that clients can not solve themselves without the API (In
other words, we should avoid "utility" or convenience Classes/methods unless there is a good reason).
3. Why is the API in WTP? That is, if its not obvious, be sure its clearly stated why in WTP as opposed
to base Eclipse, or some other project. [if doubt, should be perhaps be internal or provisional for WTP
4. Is the functionality provided in a way that can evolve?
5. Does the API "expose" underlying implementation in a leaking API fashion (for example, something that
uses EMF under the covers, should not require clients to program to EMF. As another example, if a
particular DOM implementation was changed in the future, clients should not have to change). -- except
some cases defined by standards
6. Does the WTP API violate any pre-req API (would seldom be allowed). or does it's implementation
require violation of pre-req APIs (which would be a highly questionable practice). --- if components
leads need to use "internal" for implementation, feel free to initiate contact with Architecture Group
to help document/resolve cross project/component issues
7. Does the component pre-req or export anything inappropriately? (For example, nothing in WST should
pre-req JDT). The rule is ... typically don't export anything unless it is required by your API.
8. UI related API is to be minimized. In keeping with typical software practices, the UI can change a
fair amount from release to release, but underlying models should be compatible. (For example, what's a
wizard in one version might be a property page in the next, so if clients started to depend on a
particular wizard that might "lock in" an undesired API).
9. Care should be taken in providing API that's intended to be subclassed or extended (its hard to do in
a way that's evolvable). Feel free to request Arch. Group review of any specific cases anyone would like
help with.
10. Lastly, its very important to assess and hear community feedback on whether or not WTP API is
adequate? (ie. arch group can help consult if a team is concerned they are being "over cautious"). While
some inadequacies can be included in future releases with evolution of the API ... some assessment of
risk is helpful, if "big changes" anticipated since sometimes to become adequate, and API must change its
Community feedback about even this list will be welcome and even more so about concrete cases
of particularly good or possibly poor examples of our success in achieving them.