archive/working/development/meetingNotes/20050324.txt - webtools/webtools.releng - Gitiles

 Attendees: David, Kevin, Naci, Ted, Chuck
 Special Guests: Tim DeBoer, Craig Salter


 Agenda:

 Two Problem areas discussed and resolved.

 88013 csalter@ca.ibm.com david_williams@us.ibm.com [arch] Should tabbed property sheet be API
 88016 deboer@ca.ibm.com david_williams@us.ibm.com [arch] Should web browser (view) be in base?

 One resulted in WTP request for Eclipse 3.2
 89087 Platform-UI-Inbox@eclipse.org david_williams@us.ibm.com 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
 1.0]

 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
 fundamentals.

 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.
	Attendees: David, Kevin, Naci, Ted, Chuck
	Special Guests: Tim DeBoer, Craig Salter


	Agenda:

	Two Problem areas discussed and resolved.

	88013 csalter@ca.ibm.com david_williams@us.ibm.com [arch] Should tabbed property sheet be API
	88016 deboer@ca.ibm.com david_williams@us.ibm.com [arch] Should web browser (view) be in base?

	One resulted in WTP request for Eclipse 3.2
	89087 Platform-UI-Inbox@eclipse.org david_williams@us.ibm.com 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
	1.0]

	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
	fundamentals.

	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.